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

["Joseph S. Myers" <joseph at codesourcery dot com>]

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.)

-- 
Joseph S. Myers
joseph@codesourcery.com