Re: [boost] Possible Errors in Boost Config (mostly documentation)

From: John Maddock (jm_at_[hidden])
Date: 2002-11-11 06:50:45

> I found some documentation problems in the Boost Configuration
> Reference, and possibly some obsolete symbols in the configuration
> headers.  These comments all apply to the boost_1_29_0 release.  Here
> are the specifics:

Thanks!

> 1. The config headers may define
>
>   BOOST_NO_STD_WSTREAMBUF
>
> which is not mentioned in the documentation; however, the documentation
> mentions
>
>   BOOST_NO_STD_WSTREAM
>
> which is not defined in any config header, but is used in
>
>   <boost/format/format_fwd.hpp>
>   libs/format/test/format_test1.cpp

I think we ended up changing the name at some point - it needs to be changed
to
BOOST_NO_STD_WSTREAMBUF throughout.

> 2. No config header defines BOOST_HAS_PTHREAD_YIELD, although it is
> described in the documentation.  It is used in some tests and one place
> in Boost Threads.

I think pthread_yield is only required on some obsolete unix systems, most
now have the POSIX standard sched_yield.  The configure script will pick
this one up if the platform requires it.

> 3. BOOST_COMPILER_VERSION is defined in the config headers, but is
> undocumented and unused.

Good point, I think that Beman added this one for a couple of compilers in
order that BOOST_COMPILER would give more readable output - in other words
it's an internal detail, no documentation needed, you shouldn't use it.

> 4. BOOST_DECL is defined in the config headers, but is undocumented and
> unused except in test libs/config/test/config_info.cpp.

These are a hang up from the previous config system, I think that the only
code that used them has now been removed, so unless anyone objects I'll
remove these....

> 5. BOOST_HAS_MPTASKS is defined in the config headers, but is
> undocumented.  It is used only in Boost Threads.

Can whoever is responsible for that one please supply docs and a test case?

> 6. BOOST_NO_CWTYPE is defined in the config headers, but is undocumented
> and unused.

Thanks: it's typo in the one place it appears: it should be BOOST_NO_CWCTYPE

> 7. BOOST_STD_EXTENSION_NAMESPACE is defined in the config headers and
> widely used, but is undocumented.

I'll get it added, thanks.

> 8. The documentation states, in guidelines to Boost authors,
>
> "Boost files that use macros defined in <boost/config.hpp> should have
> sensible, standard conforming, default behavior if the macro is not
> defined. This means that the starting point for porting
> <boost/config.hpp> to a new platform is simply to define nothing at all
> specific to that platform. In the rare case where there is no sensible
> default behavior, an #error message should describe the problem."
>
> Aren't there some macros, such as BOOST_STATIC_CONSTANT,
> BOOST_USE_FACET, BOOST_NESTED_TEMPLATE, etc., that you can count on
> always being defined to something, even on (the mythical) fully
> standard-conforming platforms?

Yes, the inevitable exceptions :-)  These all get defined to sensible
defaults in suffix.hpp if they're not otherwise defined, they're exceptions
because they simplify code, rather than going through the usual:

#ifdef SOMTHING
.. code
#else
  ... code
#endif

all over the place.

John Maddock
http://ourworld.compuserve.com/homepages/john_maddock/index.htm