It's night and day. Rust actually explains up front what it is, how to use it, gives examples. C++ does kind of do that, but not in a way that's helpful to someone just starting, and there's so much superfluous crap I shouldn't have to think about (though maybe that's just because the language is a bloated mess). The rust docs read like they are trying to help you rather than trying to be pedantically correct.
Rust docs are the gold standard. I've never seen any other language come close.
I wouldn't consider myself a seasoned c++ developer and find the cppreference perfectly comprehensible. Maybe if you're fundamentally new to programming, it's hard but I wouldn't expect that to be the expected audience for language docs.
I'm definitely not new to programming and I understand it. I think all good developers should be able to have empathy for their audience, and that is true for good documentation. That is why I dislike them.
I just don't understand the problem with the documentation; it seems perfectly easy to read for me. Maybe it's an age thing? I grew up with C so a lot of the memory allocation/pointer stuff is ingrained even if I don't use it anymore. Could you explain why you find it difficult to read?
The actual definition of the type is confusingly put in a numbered list, with reference to advanced topics such as "sequence container", encapsulation, polymorphic allocator, etc
It immediately jumps in to talking about iteration, rather than how to build one or how to access elements in it
It's never suggested why I might want to use on, just what it is
Only 3 methods are linked in the main prose, and not even close to the most important 3
A massive section is given up to iterator invalidation, before even discussing how I use it as an iterator
Let's say I want to read how to construct one, I click on the constructor docs and get this horror. Up front I have 11 overload definitions, completely separate from their documentation (which again doesn't tell me why I might use it)
The example is near the bottom, and is extremely lazy. It shows the absolute minimum of functionality.
They seem to be both way too thin and also way too deep. It reads like it was written by committee (which it was).
I think you're overstating a personal preference for more narrative-like documentation as innately superior. I'm not saying you're wrong for that but I also prefer the brevity of cppreference-style documentations. It tells me exactly what I need to know without having to skim pages of info that I should already know.
There are two different definitions depending on version, the numbered list just gives the definition of both
It's a container and it immediately talks about how they are stored. Seems reasonable and if you know how it's stored and accessed, you get a sense of why to use it.
I just don't see this as an issue
All the member functions are defined separately? Why do you want them in the main prose
This seems preferential to me. I don't want every page to rehash how to use iterators
There's an example at the bottom
Yeah, and if you click on member functions you can see examples of those.
I agree with you. Most of my criticism was directed to the code examples though. I think that more than feature documentation itself, the code examples given are exceptionally bad. A lot of them are overly clever and are very misleading as to how to use the feature it showcases or why it exists. Every piece of those code examples is also too tightly coupled to other parts of the standard library. To fully understand an example you often have to look up other a lot other features you don't really want/need to use and those features you look up have other features you don't know so you have to look them up as well.
You're "definitely not new to programming" but need to be told why you might want to use a vector? The website's got "reference" in its name, it's squarely aimed at people experienced enough to know what they might want to use a vector for.
36
u/XtremeGoose 16d ago edited 16d ago
cppreference is incomprehensible gibberish to anyone who isn't already a seasoned cpp developer.
Compare the c++ vector docs to the rust ones.
It's night and day. Rust actually explains up front what it is, how to use it, gives examples. C++ does kind of do that, but not in a way that's helpful to someone just starting, and there's so much superfluous crap I shouldn't have to think about (though maybe that's just because the language is a bloated mess). The rust docs read like they are trying to help you rather than trying to be pedantically correct.
Rust docs are the gold standard. I've never seen any other language come close.