linux-kernel - Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

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]

Date:	Thu, 08 Aug 2013 10:13:23 +0800
From:	Chen Gang <gang.chen@...anux.com>
To:	Rob Landley <rob@...dley.net>
CC:	Joe Perches <joe@...ches.com>, 'Jiri Kosina' <trivial@...nel.org>,
	Paul McKenney <paulmck@...ux.vnet.ibm.com>,
	"dhowells@...hat.com" <dhowells@...hat.com>,
	Thomas Gleixner <tglx@...utronix.de>, davej@...hat.com,
	Arnd Bergmann <arnd@...db.de>,
	David Miller <davem@...emloft.net>,
	"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	Michael Kerrisk <mtk.manpages@...il.com>
Subject: Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild"
 and "uapi/linux/Kbuild"

Hello Rob:

Maybe I misunderstand what you said (if so, I am sorry for it).

At least for me, what you said is valuable to get additional discussion,
but it seems better to start a new thread for it and also cc to
linux-doc mail list.

If so better include me in cc list, thanks.  ;-)

If you think still suitable to discuss about it in this mail thread,
please continue, at least, I still welcome.  :-)


Thanks.

On 08/07/2013 04:48 PM, Chen Gang wrote:
> On 08/07/2013 03:32 PM, Rob Landley wrote:
>> On 08/06/2013 12:31:43 PM, Joe Perches wrote:
>>> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
>>>> "include/uapi/" is the whole Linux kernel API, it is important enough
>>>> to get more global explanations by comments.
>>>
>>> It'd probably be useful to have more descriptions
>>> of uapi in the Documentation directory too.
>>
>> I'd rather have comments in the headers that get exported to userspace
>> and then have other forms of documentation generated from that by some
>> process similar to "make htmldocs". Otherwise you've got two places to
>> keep in sync.
>>
> 
> At least for me, it is a good idea, although UAPI files is rarely
> changed (may add new item, but few modifying the existing items).
> 
> And for our case, it is summary comments for directory organization for
> all UAPI files, so in my opinion, it is still necessary to give summary
> comments in Kbuild.
> 
> In Linux user mode or another OS which share the same files of UAPI,
> they do not care about our kernel's Kbuild, for they have their own
> directory organizations which may different with Linux kernel's.
> 
>> (Really the guy you've got to keep in the loop about this is Michael
>> Kerrisk. The section 2 man pages are the current best reference on UAPI
>> stuff...)
>>
> 
> As far as I know, the section 2 man pages is already for it (e.g. man 2
> setfuid, man 2 open, ...).
> 
> Do you mean currently it is only for some of system calls (part of
> UAPI), not for the whole UAPI ?
> 
> 
>> Rob
>>
> 
> 


-- 
Chen Gang
--
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/