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: <a7c8cfc9520d49749f10c78e05b09cd5@CY1PR0301MB0748.namprd03.prod.outlook.com>
Date:	Fri, 19 Sep 2014 18:25:06 +0000
From:	Stuart Yoder <stuart.yoder@...escale.com>
To:	Alexander Graf <agraf@...e.de>,
	Jose Rivera <German.Rivera@...escale.com>
CC:	Kim Phillips <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>,
	Scott Wood <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



> -----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@...uxfoundation.org>; <arnd@...db.de>; <linux-kernel@...r.kernel.org>; Wood
> Scott-B07421; <linuxppc-release@...ux.freescale.net>
> 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@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/