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. Kim -- 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/
