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: <f803a62b35ad46ebbe56b06b27766dee@CY1PR0301MB0748.namprd03.prod.outlook.com>
Date:	Fri, 19 Sep 2014 00:18:44 +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

+/**
> >>> + * @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.

If doxygen is not allowed, it would be nice to see checkpatch updated to complain.

Thanks,
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/