Re: [PATCH v3 01/24] Feature test macros overhaul: sys/features.h

[Yaakov Selkowitz <yselkowitz at cygwin dot com>]

On 2016-03-16 11:36, Craig Howland wrote:
>       This all makes things more consistent (which is sorely needed),
> but it seems to be lacking one major aspect:  documentation in the
> source.  The email points to FEATURE_TEST_MACROS(7), but the newlib
> developers and users are in the dark as to how to properly use this new
> method--the man page is not mentioned anywhere in a file, for example.

feature_test_macros(7) only covers the public side of this, and while it 
is a nice explanation of the various standards, it is not strictly 
necessary in order to know how to use it.  If you want more extensive 
documentation, then the proper public macro(s) should be mentioned in 
the SYNOPSIS of each function, as is done in throughout the Linux man-pages.

> The prior method at least partly used user-level defines that were
> self-explanatory, and this actually takes a step backwards from that.

No, this is a step forward both in terms of consistency and correctness.

> For example, __STRICT_ANSI is a compiler predefine that can be looked
> up, and _POSIX_C_SOURCE can be found in POSIX. However, the user is now
> confronted with the *_VISIBLE defines, but just what these mean is not
> clear.

Users are *not* "confronted" with __*_VISIBLE, as those are private 
(internal) macros, nor is that naming scheme new.

> (Some are more so than others, as ISOC99_SOURCE is pretty
> obvious, but what does ATFILE_VISIBLE mean?)

You're mixing public and private (internal) macros here.

> In a similar manner, if a developer adds a function, what is the proper
> way to label it with *VISIBLE?

The same thing I did to get this far: look at the Linux man-pages, and 
use the __*_VISIBLE macros which correspond to the public macros 
indicated therein.

>       The comments at the start of features.h give a reasonable summary
> for an informed user (so there is something on the user level), but
> developer guidance on using VISIBLE is essentially non-existent.

Note that's not a regression.

--
Yaakov