Re: [hash2] Formal Review Begins

From: Peter Turcan (peterturcan_at_[hidden])
Date: 2024-12-09 23:00:31

Matt, et al,

I have read over the documentation for the Hash2 library, and what follows
are my notes.

First and foremost, *I appreciate the effort and detail that has gone into
getting the documentation this far - no mean amount of work*. Also
appreciate that there are plenty of links to external topics and many
examples - all helpful, and perhaps some of the things I mention here are
already planned.

*General Points:*
1. Just a little confused as to the name "Hash2" when there is no "Hash1" ?
Perhaps this was explained earlier and I missed it.

2. With all the doc in one single page I found the absence of an obvious
Search function awkward, but perhaps this is forthcoming through another
effort? I found I wanted to search for words such as "required",
"optional", "hash_append" and so on.

3. I agree with other commenters that the all-in-one-page approach is
daunting ("Grandmother's fruitcake"). Would have liked to see at least all
the top level topics as separate pages, though ideally Reference material
is better as one page per construct (class, method, property, structure) so
a dev can link to that page when they are working hard on an implementation
of the construct.

*Contents:*
1. The "Supported Compilers" section should be moved up after the Overview,
as part of a section "Getting Started with Hash2".

2. The Getting Started section should work through one example that
a newcomer to hashing can understand:
a. installing Hash2
b. linking/compiler requirements or options
c. provides a short but meaningful example
d. running and explaining the output

3. The Getting Started section could use a "Common Errors and Issues"
section detailing the most likely errors, misconceptions or stumbling
blocks and how to respond. And/Or a Troubleshooting section for the library
as a whole.

4. Consider following this with a "Tutorial" section - repeating the steps
of the Getting Started section, but with a meatier and potentially useful
example.

5. Usage Examples, the code examples have almost no comments - would
benefit from being extensively commented.
- same for other code snippets throughout the doc - though "Examples" takes
priority

6. The "Example" sections in the Reference would also benefit from a
sentence/para explaining what the example does, in particular noting any
gotchas or potential pain points.

7. In the doc:  Described classes (using Boost.Describe).

Boost.Describe should be a link to that libs docs. Same for mentions of
other libraries.

8. In the block_size section for Hash Algorithm Requirements, there are the
two paragraphs (my bold):

Cryptographic hash functions provide a block_size value, which is their
block size (e.g. 64 for MD5, 128 for SHA2-512) and is *required *in order
to implement the corresponding HMAC.

block_size is an *optional *requirement.

These statements appear to be contradictory - and there is no such thing as
an "optional requirement". There is such a thing as an "optional
parameter/setting". Consider searching the doc for the phrase "optional
requirement" and amending. Consider searching for other "required/optional"
statements and verify there is no ambiguity.

9. Nit. Replace "e.g." with "for example, " - it is so much easier to read.
Same for other contractions (i.e. = "that is" etc. = "and similar/so on").

10. Should there be an "Acknowledgements" section near the end - design
input, testers?

I am the technical writer for the Cpp Alliance.

Hope this helps.

Best of luck with the project.

- Peter Turcan

On Mon, Dec 9, 2024 at 12:45 PM Matt Borland via Boost <
boost_at_[hidden]> wrote:

>
> > I vote to ACCEPT this library.
> >
>
> > Zach
> >
>
> Zach, thank you for your review and comments.
>
> Matt
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>