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@lists.boost.org> 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