ericniebler
commented
2 years ago I am very sympathetic to what you say here and I'm sorry about your lost 40 minutes. The reason the link to accumulate takes you to the one in the meta namespace is because the docs are autogenerated with Doxygen, which is a pile of broken hacks. The reference section needs to be rewritten by hand. It's a huge job that I just don't have time for, sadly.
I've been looking for someone(s) to take over the maintenance of range-v3, but have been unsuccessful so far.
stellarpower
This is clearly an impressive library, and no doubt it is implemented very efficiently, but given the size it is now, and the level of complexity in the design needed to make it work efficiently, it is not the easiest to use. There are complicated mechanisms working under the hood and the compiler errors are long. This is to be expected, of course, but given the number of people praising this library, I feel the documentation now really needs to be improved.
As an example, I have just lost about 40 minutes, amongst other things, trying to find out why the compiler can't find accumulate as in the examples on the index page. If I click on the link in the code, it takes me to the page for the
metanamespace. Most things are a view or an adaptor, so I have been trying to separate the two in my code.accumulateapparently isn't either, but it's not clear what it is.This seems to be a regular pattern (and one that many libraries suffer from, to be fair, I'm looking at you, OpenCV) - the introduction, the basic examples are good. But if I want to find out more about e.g.
remove_if, it takes me straight into the bowels of the library here. Let's pretend I don't know if I should return true to keep an item, or true to remove it, and want to find this out. I don't see any obvious place I can find more detail on what this algorithm does, what parameters it accepts, beyond that quite involved template signature. There isn't enough documentation in the middle grond that explains the mechanisms of individual ranges andwhat arguments they need, without throwing you into the inner workings, and there isn't enough detail of the conceptual overview of what is going on, when ready to move beyond the basics. Right now, I'd like to pass around a view in my class hierarchy, for example. There presumably is an easy way to do this, but all the examples are short snippets at top-level, so they can useauto. I'm not a novice, either, I have over a decade of programming in C++, but to be able to make more than trivial use of a library, as user-programmers without an existing understanding of all the implementation details, we need something we can read that gives a good overview of how everything works beyond the first introductions, and before diving into implementationdetails and documentation for individual classes, functions, etc.I appreciate docs are always the last thing on everyone's mind, myself included, that it is mentioned that this is a known issue and that this may sound like a rant, but for me, I would really like to use this library more in my code, and at this point I just can't justify spending half an hour or more when I'm at work, and could write a for loop in three minutes, even if this is inefficient. About half of my code for range use has ended up commented out because I'm left just second guessing why it doesn't compile, and ditch it and come back later when my mind isn't foicussed on the task at hand. This is a great shame, and I know how excited the community is about ranges, hell, of course it is, anything new in the world of containers gets C++ developers excited, so at this stage I think overall that the documentation isn't doing the library justice.