Re: [PATCH] Add "Inter-process Communication" chapter to the glibc manual.

["Carlos O'Donell" <carlos at redhat dot com>]

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.