Re: Multi Mini-Review Begins Today

Matt, Alfredo

Had another good look at your documentation for Boost.Multi. I do like the
more conversational style and use-case focus of the Introduction and the
basic structure - Introduction - Requirements - Installation - Getting
Started - etc.

I can always find things to comment on:


*How to Guides*Only one guide so looks odd, perhaps move its one guide "How
to Fill Elements....." to "Advanced Usage" at an appropriate spot and
delete the How to Guides heading. OR perhaps delete the "Advanced Usage"
heading and replace it with "How to Guides" as that seems more accurate.

Advanced Usage in the menu turns into "Tutorial" in the text. Perhaps
choose one title ("How to Guides" might work the best) and use this one
title to replace "Advanced usage" and "Tutorial" - as it seems the usage is
not particularly advanced, nor is it laid out as a step-by-step tutorial.


*Inconsistent capitalization in headings:*Personally, I prefer all
non-noise words to be capitalized, for example:  "Slices and Strides" is
good. However, on the following page the capitalization is inconsistent,
for example:
"Addressing subarrays" - I would have preferred this to be "Addressing
Subarrays" - makes the heading look more assertive:
https://correaa.github.io/boost-multi/multi/tutorial.html#tutorial_const_correctness

*Headings in general* are not great, just labels such as "Restrictions".
For the How to Guides/Advanced Topics" I would have preferred dynamic
action headings - replacing labels such as "Restrictions" with a more
compelling "Delay Evaluation with Restriction Arrays"
Replace "Const-correctness" with "Disallow Mutation with Const-correctness"
Replace "Uninitialized vs. Initialized Elements" with "Avoid the Pitfalls
of Uninitialized Elements" or similar
Replace "Conversions" with "Change Behavior with Conversions"
Replace "Slices and Strides" with "Slice and Stride your Arrays"
Replace "Indexing" with "Index rather than Iterate through your Arrays"
- same idea for all the other headings in this section - active headings
are not needed in Reference style sections (including Interoperability)
https://correaa.github.io/boost-multi/multi/tutorial.html#tutorial_const_correctness

*Technical Points*
Choose one or the other with Technical Points (Design Rationale)  - either
work, brackets do not work well in headings

*Reference (auto generated)*
Many API components are missing Descriptions, for example:
https://correaa.github.io/boost-multi/multi/reference/index.html

Member Functions are not alphabetically listed - for example:
https://correaa.github.io/boost-multi/multi/reference/boost/multi/elements_iterator_t.html
https://correaa.github.io/boost-multi/multi/reference/boost/multi.html

Not quite sure why "deprecated" types should be mentioned at all in a newly
released library?:
https://correaa.github.io/boost-multi/multi/reference/boost/multi.html

*Why Is the C++17 Standard Chosen as the Minimum?*
nit: I think you mean "extensively" not "intensively" in the following:
The implementation uses if constexpr intensively.

In general, I think users will be able to find what they are looking for
within your documentation so I would vote to ACCEPT the library from the
doc point of view.

I am the Technical Writer for the CppAlliance.

- all the best and good luck!
Peter Turcan







On Sun, Aug 9, 2026 at 8:29 AM Matt Borland via Boost <[email protected]>
wrote:

>
> Which I why I choose to vote CONDITIONALLY ACCEPT the library due to the
> substantial improvements and needed improvements it has received.
>
> Best,
> Amlal El Mahrouss
>
> ## References:
>
> - [1]
> https://github.com/correaa/boost-multi/commit/74fa6d6762255c9239a7311c9b1765b6d66e976e
> - [2] https://github.com/correaa/boost-multi/issues/153
>
>
> Thank you for taking the time to review Amlal
>
> Matt
> _______________________________________________
> Boost mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
> Archived at:
> https://lists.boost.org/archives/list/[email protected]/message/OBDHTCKKY4S3GGJ7N4NTALJONGYZZM7U/
>
_______________________________________________
Boost mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
Archived at: https://lists.boost.org/archives/list/[email protected]/message/O5ZYY5MR3JGA7E6ZDFEM5WZUDOY4IGE5/