Matt, Alfredo, et al. Here is my review of Boost.Multi documentation. For the record I am the technical writer for the C++ Alliance. 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. My notes: 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. 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.* 3. Nit: typo - "althoug": The library’s primary concern is with the storage and logic structure of data. It doesn’t make algebraic or geometric assumptions about the arrays and their elements. (*althoug* they are still good building blocks for implementing mathematical algorithms, such as representing algebraic dense matrices in the 2D case, or tensors in the general case.) 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. 5. Nit. Odd, truncated sentence in the table section: Why is dimensionality static and the sizes are dynamic? *Sizes are fixed or * 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. 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] 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. 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. 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. 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. 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. 13. Nit. Typo: why the colon? Note that this is also different from creating a named *reference:* 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. 15. Typo - sentence starting with lower case: *which* uses the default Thrust device backend ( 16. Typo - upper case C needed: Why is *c++*17 chosen as the minimum? 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 Perhaps use Title case for headings - capitalize nouns, verbs, adjectives, not articles, prepositions or conjunctions. Avoid punctuation if at all possible. 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"? 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. 20. Appendix - How to's is not appendix material - belongs after or part of tutorials (perhaps renamed to "Advanced Use Cases" or similar). 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. - best and good luck with the project! - Peter Turcan On Sun, Mar 8, 2026 at 7:49 AM Matt Borland via Boost <boost@lists.boost.org> wrote:
Therefor, I recommend to CONDITIONAL ACCEPT the library with the following conditions:
1. Rename the types so they are intuitive to C++ developers, for example as described above. 2. Remove or generalize (make available to all N) functions currently only available for N =1 (e.g. data()) 3. Make array_ref and subarray the same type. 4. Provide algorithms as free functions. 5. Remove the `extensions()` function if it is the same as a C for-loop. 6. Remove `dynamic_array` or give it a better name like `unique_array`.
Thank you for your review and comments Klemens. Your acceptance conditions are noted.
Matt _______________________________________________ Boost mailing list -- boost@lists.boost.org To unsubscribe send an email to boost-leave@lists.boost.org https://lists.boost.org/mailman3/lists/boost.lists.boost.org/ Archived at: https://lists.boost.org/archives/list/boost@lists.boost.org/message/VMXE23M3...