Boost Review: documentation improvements

[jzmaddock]

Docs need a TOC

"A short example of the basic usage:" - would be better to explain what the
example shows, even if it does seem obvious - make it clear for the
first-time user of this type of library.

As finance has been explicitly named as a compelling use-case, perhaps add
a meaningful (commented) finance example to the "Basic Usage" section. Or,
move the Financial Applications section up here - or both.

API Reference

Add an intro sentence as to what is available in the reference. Such as
"this section contains complete details on all the types, structures,
enums, constants and macros that are defined in this library" - make sure
that this sentence is true - have you added complete details on all this
stuff - no matter how peripheral they may be.

Good to see links to the API components.

Not sure why there is / see 3.2.8 / in that section, yet "3.2.9" does
not. Perhaps remove the "/* see 3.2.8 */ comment - the introductory comment
should do it. However, ensure there are NO exceptions to a general
statement like this. If there are, add a comment to the individual entry to
illuminate.

Perhaps add a bit more information to the Formatted input: section - OK
these are "locale dependent" but what do they do? I assume take an input
stream of characters - but consider explaining this and what terminates the
input stream? And the same comment for the output.

The *Description *of *Decimal32 *is given as a list of bullet points,
whereas the information is more suited to a table. The first column would
be something like "Attribute" the second "Value", such as:

Attribute Value
Storage width 32 bits
Precision 16 decimal digits
Max exponent

• the point is: bullet points are overused and the content suggests a
  table. Tables look nicer than bullet lists.

Same comment on bullets versus tables for all the other entries in the API
reference.

For all the functions, consider listing the Errors and Exceptions that
might be thrown - if any. For maximum value, consider adding what to do
about it if a particular error is thrown.

For functions, add an introductory sentence under the name of the function
stating what it does - even if it seems obvious. If there are any
limitations or gotchas this is a good place to articulate them.

*cfloat support *- syntax style and coloring appears to have been lost.

Macros - does describe what is disabled or defined, but consider adding a
sentence as to why you would do this. "Disabling the use of I/O streaming
enables........what?" Same for all the other macros. Add the use-case or
benefit.

Examples
Add a sentence, or two, as to what the example shows. Great if limitations
and gotchas are noted here too. For example "Generic Programming" - great
there is example code but what does the example show?

Financial Applications
Great - but consider moving much closer to the top of the documentation.
Example use cases are some of the first things a dev wants to see.

Design Decisions
Perhaps move this section ABOVE the API Reference. It is short and
explanatory as to the thinking behind the library, and is important to
understand early on.

References and Copyright etc. are OK at the end of the doc.