Re: [PATCH 3/3] manual: Add new header and standards annotations.

[Joseph Myers <joseph at codesourcery dot com>]

On Wed, 30 Nov 2016, Rical Jasan wrote:

> I don't think I'm completely following this.  Is this a redundant test,
> then:
> 
> ./math/bits/math-finite.h:#if defined __USE_MISC && defined __USE_ISOC99

Formally it's redundant.  The use of __USE_ISOC99 there is to mirror the 
conditions under which bits/mathcalls.h is included to declare float and 
long double functions at all (see my comments in commit 
3bfee8beb8caa939020d942dfa405a3d98975749).  Arguably bits/math-finite.h 
should be merged into bits/mathcalls.h (i.e. have a way for the macros 
there to map to the __*_finite functions when appropriate), though that's 
complicated by the separate ia64 version of bits/math-finite.h.

> My practical question is, if MISC is nonstandard, what would we document
> in @standards?  Just MISC?  I see it replaces deprecated feature test

My suggestion was DEFAULT.

> macros _BSD_SOURCE and _SVID_SOURCE (or rather _DEFAULT_SOURCE does,
> which is the only thing that sets __USE_MISC).  Would we not want to
> document that something came from BSD, for example?  (Also see comment
> below about handling deprecation.)

I'd say any such historical information about sources of functions should 
go in free text.  Likewise if we say anything about a function that was 
BSD or SVID or GNU before it was adopted by POSIX, @standards would only 
mention (the relevant version of) POSIX, but free text could say more 
about the history.

> What do you think about handling the common, "This function is a GNU
> extension.", throughout the descriptions?  Would you remove those in
> lieu of "Standards: GNU (...)"?  It's one of the few consistent and
> widespread phrases throughout the manual.

Yes, I think free text describing standards could be removed when it 
doesn't give any more information than the @standards text.  Likewise free 
text saying what header has a declaration.

> Also, what about deprecation?  I saw the exceptional case of gets
> mentioned recently.  There are quite a few BSD things the manual warns
> about being deprecated.  Maybe anything that can't be coloured properly
> in @standards just deserves a nice paragraph somewhere in the description.

Indeed, something not handled by @standards needs free text.

Eventually it would be good for all of the conform/ data, the header 
contents and the standards annotations to be cross-checked against each 
other by the glibc testsuite.  (conform/ and headers are already checked 
against each other.  conform/ should correspond closely to the manual for 
standards properly handled in both, if everything including structure 
elements gets annotations in the manual.  Correspondence between the 
headers and the manual is necessarily weaker, because of symbols exposed 
by headers where the standards permit but don't require this and we don't 
want to define it to be a stable API for those headers, but checking such 
a correspondence is still useful and can cover more standards than 
conform/, including DEFAULT and GNU.)  That includes automatically finding 
undocumented interfaces, for which bugs should then be filed if not 
already open (we have extremely out-of-date scripts/documented.sh for 
listing undocumented functions as well).

When you're checking that the sets of implemented and documented 
interfaces match, you get into needing to document that an interface is 
only available in certain configurations of glibc (e.g. Linux-specific 
interfaces).  Thus I can see us eventually wanting macros (whether or not 
variants of @standards) that will insert text indicating how an interface 
is system-specific, for use by such checks to avoid complaining that an 
interface is documented that doesn't actually exist.

-- 
Joseph S. Myers
joseph@codesourcery.com