linux-kernel - Re: [PATCH 1/4] drivers/bus: Added Freescale Management Complex APIs

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 linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20140919155802.d5d8e80c7aff3b2ae81c6b50@freescale.com>
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/