The main overview section doesn't include an introduction for the purpose of the library. The table there doesn't serve the purpose as well since it is the text of the third column of each row that, in aggregate, documents the purpose.
I suggest the following:
Boost.Integer provides integer type support, particularly helpful in generic programming. It provides standard C99 integer types, such as might be found in <stdint.h>, without requiring that header. It provides the means to select an integer type based upon its properties, like the number of bits or the maximum supported value, as well as compile-time bit mask selection. There is a std::numeric_limits derivate that provides constant expressions for min and max. Finally, it provides two compile-time algorithms: determining the highest power of two in a compile-time value; and computing min and max of constant expressions.
Added, thanks.
(Why are some headers in boost/integer and others in boost? That's awkward.)
Sigh, no idea, I agree though.
Overview
s/specifications are/specifications for these types are/ s/The 64-bit types...in the C++ standard./The 64-bit types required by the C standard are used as models. If <stdint.h> is available on a given platform, those typedefs are used as the definitions for the boost namespace typedefs. Otherwise, or if long long is not provided, <boost/cstdint.hpp> provides its own definitions.
Not quite, if there's no long long then boost/cstdint.hpp can hardly provide it's own definitions ;-) Updated to, hopefully, make this clearer: "The specifications for these types are based on the ISO/IEC 9899:1999 C Language standard header <stdint.h>. The 64-bit types required by the C standard are ['not required] in the boost header, and may not be supplied for all platforms/compilers, because [^long long] is not [yet] included in the C++ standard."
integer_traits has all private members. Should it have been declared a struct?
Oops, or at least have a "public:" inserted somewhere...
Integer Type Selection
These are not doc comments: I would think adding uint_fast_t would be less confusing, though using int_fast_t with unsigned types must probably continue to work for backward compatibility. The output type ought also to be accessible as "type."
Will change to use ::type. I'm not convinced about adding yet another trait, when this one will do though...
Sized Types
This is not a doc comment: The output type ought to be accessible as "type," though you'd probably need to retain "least" for backward compatibility.
Actually, these are "bag" traits classes with three members: ::least ::fast ::exact I'll update the table to make this more explicit.
Group Bit-Mask Class Template
s/lowest bits of a certain amount/lowest Bits bits/
(I couldn't figure out what the original phrasing meant and took a guess.)
Me neither :-( Changed to use the definition - 2^Bits - 1.
Example
What in the world is "is_it_what" supposed to convey? The name is nonsensical to me.
Me too, I've removed the example. Frankly I'm not sure if anyone is actually using the integer-masks, compile-time log2 or min/max functions, I don't really see the point, and the examples given don't help much :-( Many thanks, I've applied the other suggestions BTW - a big help - thanks! John.