Hi Peter, thank you for your review
Message: 3
> Date: Mon, 9 Mar 2026 13:39:02 -0700
> From: Peter Turcan <peterturcan(a)cppalliance.org>
> Subject: [boost] Re: [multi] Formal Review Begins
> To: "Boost developers' mailing list" <boost(a)lists.boost.org>
> Message-ID:
> <CABnUvfJMsz9AEa6epdBGC0=
> S4fEMcum5wbathXc+-zrXG5rqZw(a)mail.gmail.com>
> Content-Type: text/plain; charset="UTF-8"
>
>
> Overall, the library should be usable with the current documentation,
> though there were quite a few issues that could be considered to improve
> it. Did largely like the tone of the text, the short and frequent examples,
> the correct use of formatting for code syntax, and the overall structure is
> about right. I appreciate the effort that has been put into this library so
> far.
>
Thank you for the appreciation.
> 1. Given that standard C++ already supports multi-dimensional arrays, I
> think it could be clearer in the Introduction what this library brings to
> the developer that is missing from the Standard. I would make the
> differences explicit - what features the Standard does not support. Perhaps
> this is just a wording change - from "Features of this library that aim to
> facilitate the manipulation of multidimensional arrays include:" to
> "Features
> of this library, that are not present in the Standard, that aim to
> facilitate the manipulation of multidimensional arrays include:". Though be
> careful to add further qualification to the features if any are present, in
> whole or in part, in the Standard. Is the Standard known for making
> "unnecessary copies" for example, if so, articulate this issue. Same deeper
> explanation for your other features.
>
This suggestion is accepted, I put these two sentences:
"The following features of this library are not present in the Standard or
generally combined in other libraries:"
"For example, `std::mdspan` does not provide iterators, or generic
interoperability with the rest of the STL."
I also put a more specific things about mdspan in the Introduction.
> 2. In the Introduction again, I would have liked some more discussion on
> use cases. Multi-dimensional arrays are often used in real-time simulations
> for example, to provide physical data super-quickly without the need for
> equations or other computationally expensive approach. If there are other
> compelling examples (AI, finance, astrophysics, etc.), great to be specific
> and list them out. *This does have the effect of drawing in developers
> working in those areas - particularly if you can link the unique features
> of the library mentioned above to those use cases.*
>
Suggestion accepted:
"In many simulations, space is divided into a grid, and values are stored
at each grid cell.
For example, arrays can represent fields of physical values, such as
temperature variations within a block of material based on spatial
coordinates, or velocity fields in a fluid.
In a game, the state of board can be represented by placing pieces in a
lattice.
Arrays can also store numerical matrices, vectors, and more generally,
tensors, to perform linear algebra operations.
They can represent other abstract data structures, like network, graph, or
store data in multiple columns.
Arrays are amenable to bulk processing in computing, and also to slicing,
and reductions."
> 3. Nit: typo - "althoug":
>
>
fixed
>
> 4. In the Intro there is this statement: Multi is a header-only library
> and C++17 or later is required.
> Good info, but other requirements are scattered throughout the doc. Perhaps
> have a "Requirements" sub-heading and add OS/Compiler or other
> requirements? Later on in the doc there is: The code requires any modern
> C++ compiler (or CUDA compiler) with standard C++17 support; for
> reference,...
> All statements like this belong in the Requirements section, which itself
> should follow the Introduction.
>
I put the requirements section after the introduction
> 5. Nit. Odd, truncated sentence in the table section: Why is dimensionality
> static and the sizes are dynamic?
> *Sizes are fixed or *
>
Fixed to: "Why is the array's dimensionality hardcoded, while the array's
sizes can be defined at runtime?"
> 6. Navigation.
> Scroll to the end of a page there is no navigation options - great to see "
> *next*" and "*previous*" page links. Currently a bit tedious to have to
> relocate my place in the TOC.
>
Good point.
I think this is a good feature for Antora.
> 7. Almost no linking to outside sources. For example, all the following
> sentences could contain a link (as could many others):
> Testing the library requires *Boost.Core* (headers),
> The library works out-of-the-box in combination with the *Thrust *library.
> The library works out of the box with Eric Niebler’s *Range-v3 *library,
> *CUDA *is a dialect of C++ that allows writing pieces of code for GPU
> execution,
> or with the standard *MDSpan* *proposal *std::mdspan.
> In the *next sectio*n instead we will see an example of arrays owned by the
> library. [link to next section where this example is]
>
I added links on most places, at least at the start of the corresponding
sections.
> 8. Like the links to Compiler Explorer, but not the linking word "*online*"
> or "*live*" - doesn't say what the link is to - "Compiler Explorer" or
> whatever the title of the destination is would be much clearer.
>
I us the more explicit label "open with Compiler Explorer"
>
> 9. Nits. Remove unnecessary (and slightly condescending) words - *simple
> *or
> *a simple* adds no meaning (same for the word "very"), two examples:
> Once installed, other CMake projects (targets) can depend on Multi by
> adding *a* *simple *add_subdirectory ...
> change this to:
> Once installed, other CMake projects (targets) can depend on Multi by
> adding add_subdirectory ...
> Same for the following, and any other use of simply or very:
> —something manual indexing *simply *cannot do cleanly at scale.
>
I use the more descriptive phrase: "... by adding a *single line*
`add_subdirectory(my_multi_path)`"
I removed all instances of *simply* and *very*.
Reduced the number of *simple* occurrences.
> 10. Only add brackets where really necessary, they are an obstacle to
> smooth reading, such as here:
> (Although most of the examples use numeric elements for conciseness, the
> library is designed to hold general types (e.g. non-numeric, non-trivial
> types, like std::string, other containers or, in general, user-defined
> value-types.)
> A (mutable) array can be assigned
> (The Cereal XML and Boost XML output would have a similar structure.)
> (de)serializing [spell it out "when serializing or deserializing a ..."]
> - and many more examples.
>
All these suggestions accepted and implemented.
I will not use parenthesis clauses in the future and remove more when I see
them.
> 11. Perhaps "Getting Started" is a friendlier title than *Primer (basic
> usage)* and "Tutorials" better than *Tutorial (advanced usage)*. However,
> the tutorials are not really tutorials unless they contain numerical steps
> that a student can follow. As it is - *Advanced Usage Examples*, or a
> similar title, is more accurate.
>
I copied it from other Boost documentations, but the suggestion is accepted
and implemented.
>
> 12. Nit. Typo: Because this array is not *controled* by the library, this
> type of object is called an array-reference.
> Correct spelling is controlled.
>
> fixed
13. Nit. Typo: why the colon?
> Note that this is also different from creating a named *reference:*
>
> (probably there was code after that)
fixed
> 14. Style nit. Make reference material impersonal - not "In my experience,
> however, the following" more "Usage patterns can produce .....". Library
> documentation is formal and not a blog post, so "opinions" are mostly
> inappropriate - expressing factually with conditions is more appropriate.
>
fixed
>
> 15. Typo - sentence starting with lower case:
> *which* uses the default Thrust device backend (
>
fixed
>
> 16. Typo - upper case C needed: Why is *c++*17 chosen as the minimum?
>
fixed
>
> 17. Not crazy about punctuation in headings, for example:
> *{fmt}* - would be better as "Formatting"
> *Copy, and assigment (, and aliasing)* is ugly, "Copy, Assignment and
> Aliasing" works better
fixed
>
> Perhaps use Title case for headings - capitalize nouns, verbs, adjectives,
> not articles, prepositions or conjunctions. Avoid punctuation if at all
> possible.
>
fixed
>
> 18. Not sure about the following example code:
> Compile time evaluation
> constexpr auto trace() {
> multi::array<int, 2> arr = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}};
> arr[2][2] = 10;
> return std::accumulate(arr.diagonal().begin(), arr.diagonal().end());
> }
>
> static_assert( trace() == 4 + 2 + 10 );
>
> If arr[2][2] is 10, shouldn't the assert be "1 + 5 + 10", or have I
> misunderstood "diagonal"?
>
you are right the example was wrong, I corrected it.
>
> 19. Reference - I agree with earlier comments that the Reference should be
> more complete. Each function/method should have its own page (or section)
> to include a brief sentence on its purpose, then syntax, parameters, return
> values, errors and exceptions, remarks for a fuller description if
> necessary, and for bonus points an example, or link to an example, of its
> use.
>
Yes, the reference section needs a lot of work.
I am trying to find the right tool for this, Mr.Docs. For example. I am
looking at the example from Capy.
A peculiarity of this library is that many of the input and output
parameters are conceptual, not concrete types.
This in turn calls for a Reference for the concepts.
> 20. Appendix - How to's is not appendix material - belongs after or part of
> tutorials (perhaps renamed to "Advanced Use Cases" or similar).
>
It was a request in another review, I renamed it as FAQ.
> Currently my feelings are that this library should have a CONDITIONAL
> ACCEPTANCE that the features added are a significant enough improvement
> over the current Standard, and that those improvements are clearly
> articulated in the Introduction section of the docs. And some work on the
> Headings, Reference and Navigation issues would help a lot.
>
> Hope this helps.
>
Yes, it helps a lot. Reference requires work, but I hope I solved most of
the other problems.
Let me know if the Intro is more convincing now.
Thank you,
Alfredo
