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 for Android: free password hash cracker in your pocket

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

Message-ID: <520209FA.70409@asianux.com>
Date:	Wed, 07 Aug 2013 16:48:58 +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"

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/