On Mon, Sep 22, 2014 at 02:42:10PM +0000, Stuart Yoder wrote: > > > > -----Original Message----- > > From: Kim Phillips [mailto:kim.phill...@freescale.com] > > Sent: Friday, September 19, 2014 3:58 PM > > To: Yoder Stuart-B08248 > > Cc: Alexander Graf; Rivera Jose-B46482; Phillips Kim-R1AAHA; > > <gre...@linuxfoundation.org>; <a...@arndb.de>; > > <linux-kernel@vger.kernel.org>; Wood Scott-B07421; > > <linuxppc-rele...@linux.freescale.net> > > 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.yo...@freescale.com> 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.
You "forked" the code when you asked for it be merged into the kernel tree. You shouldn't ever have to rely on the "old" version again, so please, remove the doxygen mess. greg k-h -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
