This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH 3/3] manual: Add new header and standards annotations.
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