This is the mail archive of the newlib@sourceware.org mailing list for the newlib project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]