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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
