Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933685Ab3HHCO3 (ORCPT ); Wed, 7 Aug 2013 22:14:29 -0400 Received: from intranet.asianux.com ([58.214.24.6]:17114 "EHLO intranet.asianux.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932506Ab3HHCO2 (ORCPT ); Wed, 7 Aug 2013 22:14:28 -0400 X-Spam-Score: -100.8 Message-ID: <5202FEC3.4010408@asianux.com> Date: Thu, 08 Aug 2013 10:13:23 +0800 From: Chen Gang User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130110 Thunderbird/17.0.2 MIME-Version: 1.0 To: Rob Landley CC: Joe Perches , "'Jiri Kosina'" , Paul McKenney , "dhowells@redhat.com" , Thomas Gleixner , davej@redhat.com, Arnd Bergmann , David Miller , "linux-kernel@vger.kernel.org" , Michael Kerrisk Subject: Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild" References: <52005571.4080704@asianux.com> <1375810303.2424.28.camel@joe-AO722> <1375860749.8422.25@driftwood> <520209FA.70409@asianux.com> In-Reply-To: <520209FA.70409@asianux.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2266 Lines: 68 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@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/