RE: [PATCH 1/4] drivers/bus: Added Freescale Management Complex APIs

[Stuart Yoder]

> -----Original Message-----
> From: Kim Phillips [mailto:kim.phillips@xxxxxxxxxxxxx]
> Sent: Friday, September 19, 2014 3:58 PM
> To: Yoder Stuart-B08248
> Cc: Alexander Graf; Rivera Jose-B46482; Phillips Kim-R1AAHA; <gregkh@xxxxxxxxxxxxxxxxxxx>; <arnd@xxxxxxxx>;
> <linux-kernel@xxxxxxxxxxxxxxx>; Wood Scott-B07421; <linuxppc-release@xxxxxxxxxxxxxxxxxxx>
> Subject: Re: [PATCH 1/4] drivers/bus: Added Freescale Management Complex APIs
> 
> On Fri, 19 Sep 2014 13:25:06 -0500
> Yoder Stuart-B08248 <stuart.yoder@xxxxxxxxxxxxx> wrote:
> 
> > > From: Yoder Stuart-B08248
> > > Sent: Thursday, September 18, 2014 7:19 PM
> > >
> > > +/**
> > > > >>> + * @brief    Disconnects one endpoint to remove its network link
> > > > >>> + *
> > > > >>> + * @param[in]   mc_io        Pointer to opaque I/O object
> > > > >>> + * @param[in]    dprc_handle    Handle to the DPRC object
> > > > >>> + * @param[in]   endpoint    Endpoint configuration parameters.
> > > > >>> + *
> > > > >>> + * @returns    '0' on Success; Error code otherwise.
> > > > >>> + * */
> > > > >>> +int dprc_disconnect(struct fsl_mc_io *mc_io, uint16_t dprc_handle,
> > > > >>> +            struct dprc_endpoint *endpoint);
> > > > >>> +
> > > > >>> +/*! @} */
> > > > >>
> > > > >> this entire file is riddled with non-kernel-doc comment markers:  see
> > > > >> Documentation/kernel-doc-nano-HOWTO.txt on how to write function and
> > > > >> other types of comments in a kernel-doc compliant format.
> > > > > This is because this file is using doxygen comments, as it was developed
> > > > > by another team. Unless someone else has an objection, I will leave the doxygen comments alone and
> not
> > > make
> > > > any change here.
> > > >
> > > > Do you see any other source files in Linux using doxygen comments?
> > >
> > > Yes.  Grep around a bit and you'll see examples of it.  I grep'ed for some
> > > doxygen tags and found close to 200 source files with them.
> 
> grepping for the one in this patch above - "! @}" - returns nothing.
> 
> > > > Mixing different documentation styles can
> > > > easily become a big mess, because you can't generate external documentation consistently for the whole
> > > tree.
> > >
> > > As German mentioned elsewhere, this file is an interface to a hardware block,
> > > was written by another team targetting a wide variety of environments-- u-boot,
> > > Linux, user space, other OSes etc.
> > >
> > > We left the doxygen stuff there because while admitedly not used much, there
> > > are other examples of it in the kernel and the documentation seems useful.
> > > If it can't go into the kernel as is, we can just delete it.
> >
> > ...to be clear, we could just delete the doyxen tags.  There is no scenario
> > where I would envision anyone generating documentation from these files in
> > the kernel.  The tags are there because of where we grabbed the source from.
> > It certainly would benefit no one by conversion to kerneldoc.
> 
> except kerneldoc users :)
> 
> > However, just leaving the comments and doxygen tags alone as is would be nice.
> 
> they are incompatible with kerneldoc.

Seriously, no one is going to ever generate docs from this obscure bit of code
documenting an internal interface within this driver.  Makes no sense to convert
the comments to kerneldoc.

I completely get what you are saying with respect to comments actually documenting
kernel interfaces used by different kernel components or uapi interfaces.

The doxygen tags are there because this code originated in a different project. That
code was intended to be Linux-style compliant and complies with checkpatch --strict.
However, we can sanitize the code and remove the tags if they are causing grief.
It's too bad though, because we'll have to fork this interface code from its origin.

Stuart



--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/