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

[Stuart Yoder]

> -----Original Message-----
> From: Yoder Stuart-B08248
> Sent: Thursday, September 18, 2014 7:19 PM
> To: 'Alexander Graf'; Rivera Jose-B46482
> Cc: 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
> 
> +/**
> > >>> + * @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.
> 
> > 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.

However, just leaving the comments and doxygen tags alone as is would be nice.

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/