This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] Add "Inter-process Communication" chapter to the glibc manual.
- From: "Carlos O'Donell" <carlos at redhat dot com>
- To: "Joseph S. Myers" <joseph at codesourcery dot com>
- Cc: GNU C Library <libc-alpha at sourceware dot org>, Alexandre Oliva <aoliva at redhat dot com>, Roland McGrath <roland at hack dot frob dot com>
- Date: Wed, 26 Feb 2014 15:47:10 -0500
- Subject: Re: [PATCH] Add "Inter-process Communication" chapter to the glibc manual.
- Authentication-results: sourceware.org; auth=none
- References: <530D736A dot 1020707 at redhat dot com> <Pine dot LNX dot 4 dot 64 dot 1402261748210 dot 11728 at digraph dot polyomino dot org dot uk> <530E34F8 dot 3010403 at redhat dot com> <Pine dot LNX dot 4 dot 64 dot 1402261845541 dot 11728 at digraph dot polyomino dot org dot uk>
On 02/26/2014 01:52 PM, Joseph S. Myers wrote:
> On Wed, 26 Feb 2014, Carlos O'Donell wrote:
>
>> On 02/26/2014 12:54 PM, Joseph S. Myers wrote:
>>> On Tue, 25 Feb 2014, Carlos O'Donell wrote:
>>>
>>>> The functions include only their signature and safety information
>>>> (as audited by me). We still need to fill in the details for the
>>>> functions, but this is better than nothing IMO.
>>>
>>> Do we have a good way to list functions with only signature and safety
>>> documentation? (Like scripts/documented.sh, albeit very out of date, was
>>> supposed to provide for listing functions not documented at all. It's
>>> useful to be able to get a list of public interfaces not documented at
>>> all, to add such interfaces to the manual as placeholders for safety
>>> information, and to get a list of interfaces still needing substantive
>>> documentation - that way you have two separate incremental projects,
>>> putting in the placeholders and putting more substantive documentation
>>> there.)
>>
>> I have no automated way to do that today.
>>
>> It would be a good idea to do so, perhaps based on the ABI symbol information?
>>
>> What do you think is the best way to avoid parsing the headers?
>
> I think scripts/documented.sh - using output of "nm" - is fine for listing
> symbols in the ABI (subject to updates to what the list of relevant
> libraries is, not giving an individual email address in the output, etc.).
> Though there's a case for using objdump and abilist.awk (with
> adaptations), as in my automation for finding untested symbols
> <https://sourceware.org/ml/libc-alpha/2013-07/msg00386.html>, simply so as
> to have just one consistent mechanism for identifying public symbols.
>
> My question was more about how to generate the list of symbols with only
> placeholder documentation, which is a matter of parsing the manual.
> documented.sh might then generate two lists: completely undocumented
> symbols, and those with just placeholder documentation.
>
> (There *is* the matter of undocumented types, constants etc. in the
> headers, but those are probably harder to identify in an automated way.)
The only way to identify placeholder documentation is to work out some
kind of markup stored in texinfo comments that we can reliably parse.
I'll look into this and see if I can hack something up.
I agree we should have just one way to find public symbols.
Cheers,
Carlos.