Re: Decimal: Formal review begins.

From: Matt Borland (matt_at_[hidden])
Date: 2025-01-21 13:13:32

> John
> 

> Here is my review of the Decimal library documentation. I am the Technical
> Writer for the CppAlliance.
> 

> I appreciate the effort that has gone in to try to make this doc set
> complete.
> 

> Main issues for me are the absence of a table of contents for the docs
> (though perhaps a build script will create this?), moving the finance
> examples to a much higher profile position within the docs - as this seems
> to be the main use case, perhaps articulating other compelling (or author
> favorite) use cases, and sentences explaining what the given
> examples/functions/macros do.
> 

> Hope the following review helps!
> 

> - best
> Peter
> 

> 

> Decimal library documentation review
> 

> Great that the Use Cases is present as part of the introductory topics.
> What about other scenarios than finance - perhaps statistical applications
> (variance, standard deviation, correlations), Astronomy (planetary orbits
> over long time frames, gravitation), Mathematical Proofs (verifying
> conjectures, symbolic algebra - where exactness is key), Cryptography,
> Machine Learning (optimization algorithms, autonomous driving!), Graphics
> (to avoid artifacts)? If you have any favorites - mention, ideally with an
> example or two.
> 

> Perhaps this would be created by a build script, but the docs could really
> use a Table of Contents, with all the headers and subheaders clear to
> see. This also helps us understand the structure and scope of the library.
> 

> Odd formatting of the "Note" with Note centered vertically in the box,
> should probably be top left. Same throughout the docs - for "Important"
> topics as well as Note.
> 

> Some odd leading spaces in the examples and source code " #include"
> rather than "#include", for example.
> 

> "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.
> 

Peter,

As always thanks for your review of the docs. We will incorporate your changes shortly. Some of the weird styling (e.g. the important block) has been reported to the guys that maintain the stylesheet.

Matt