lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening PHC | |
Open Source and information security mailing list archives
| ||
|
Date: Fri, 19 Sep 2014 15:58:02 -0500 From: Kim Phillips <kim.phillips@...escale.com> To: Yoder Stuart-B08248 <stuart.yoder@...escale.com> CC: Alexander Graf <agraf@...e.de>, Rivera Jose-B46482 <German.Rivera@...escale.com>, Phillips Kim-R1AAHA <Kim.Phillips@...escale.com>, "<gregkh@...uxfoundation.org>" <gregkh@...uxfoundation.org>, "<arnd@...db.de>" <arnd@...db.de>, "<linux-kernel@...r.kernel.org>" <linux-kernel@...r.kernel.org>, "Wood Scott-B07421" <scottwood@...escale.com>, "<linuxppc-release@...ux.freescale.net>" <linuxppc-release@...ux.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.yoder@...escale.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 majordomo@...r.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists