5 ms·

To me MDN is the standard bearer for good language/library documentation. It has example uses. A description of what the function/class/object is meant for. Tel

To me MDN is the standard bearer for good language/library documentation. It has example uses. A description of what the function/class/object is meant for. Tells you information about how/if you can use it. Rust's is pretty good too. I also like Pythons. I agree cppreference is very very bad and unreadable.

danbolt 2y ago
Personally, I’ve often found cppreference has a bit of a learning curve to it. Or, at first it seems overly verbose and hard to parse. As you get more familiarized with C++’s semantics though, it feels very useful for covering a lot of ground quickly. That said, it feels like something that comes time.
senkora 2y ago
> I agree cppreference is very very bad and unreadable. The layout could definitely be better, but at least the information density is high. My take is that any attempt at C++ docs just kinda really does need all of the information that cppreference gives you. I laughed in despair at their operator==,!=,<,<=,>,>=,<=>(std::unique_ptr) picture but the thing is, C++ is just kinda like that, and I don't think any other way of organizing that information would be clearer.
- OnionBlender 2y ago
  A good alternative to cppreference is https://devdocs.io/cpp https://devdocs.io/cpp Same content, better search.
neutrinobro 2y ago
I disagree, cppreference is pretty good. The information is very complete and useful examples abound. And just because you may not understand a template operator definition does not make it useless documentation.
- consteval 2y ago
  Yes 100%. I'll expand by saying I think there's two types of documentation: references and guides. cppreference is a really, really good reference. It's complete, highly specific, and well formatted. But it's an awful guide. If I was trying to learn C++ or it's standard lib, I would want to kill myself. The problem is these two types of documentation are almost perfectly perpendicular in my mind. Meaning, a good guide is a poor reference, and a good reference is a poor guide. Hand-holding step by step instructions, popular with many js frameworks now, are great guides. But when I want to know what function X returns and under what circumstances, I don't want to prune through a guide that starts at the beginning of the universe. And often those guides will be missing huge amounts of detail to lower the complexity. So you need one kind of documentation when you start, and then another 5 years later.
lifthrasiir 2y ago
In my experience all three you mentioned have their own excellent areas. MDN covers a vast range of subjects and knowledge levels but is most laborious to maintain and I have seen some gaps due to that. Rust is also similar in those aspects, but has different "documentations" that don't fully interconnect to each other yet. Rustdoc's automatic nature is great to have a complete and working documentation, but also means that API documentations are often weaker than those of MDN as the documentation should be embedded into the source code. Python has the same issues and also inconsistencies due to the lack of language-wide automatic documentation system (Sphinx autodoc is close but still annoying). Cppreference (perhaps not intentionally) covers only higher knowledge levels and absolutely standard matters. It is of course very clear that you can't really use cppreference for learning C++ from scratch, but it is well written as long as you fit with those assumptions and its writing quality is comparable to MDN in my opinion.
- db48x 2y ago
  Why does embedding the documentation into the source code make it weaker? The author can put as much or as little effort into the documentation as they want either way.
  - lifthrasiir 2y ago
    A documentation is written for particular audiences, not always but typically users. And a user-directed documentation is largely a hindrance for whoever is actually updating a source code adjacent to that documentation, because it acts like a boilerplate template. An embedded documentation does make the absence of documentation obvious and helps towards the completeness, but not without a compromise. Ideally it should then be reordered and further elaborated externally so that it can be maximally useful. Rust has a good documentation but the general lack of such manipulation makes it often hard to navigate. For example `Vec` [1] has a lot of inherent methods with two separate orderings, where one is alphabetical in the sidebar and another is the declaration order, but none of them are actually logical and will benefit from reordering in general. Of course Rust folks are aware of this issue and have put a lengthy introduction with most important methods for each category, but that's less flexible and prone to future updates. [1] https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
deleted 2y ago
[deleted]

danbolt 2y ago

Personally, I’ve often found cppreference has a bit of a learning curve to it. Or, at first it seems overly verbose and hard to parse. As you get more familiarized with C++’s semantics though, it feels very useful for covering a lot of ground quickly. That said, it feels like something that comes time.

senkora 2y ago

> I agree cppreference is very very bad and unreadable. The layout could definitely be better, but at least the information density is high. My take is that any attempt at C++ docs just kinda really does need all of the information that cppreference gives you. I laughed in despair at their operator==,!=,<,<=,>,>=,<=>(std::unique_ptr) picture but the thing is, C++ is just kinda like that, and I don't think any other way of organizing that information would be clearer.

OnionBlender 2y ago
A good alternative to cppreference is https://devdocs.io/cpp https://devdocs.io/cpp Same content, better search.

neutrinobro 2y ago

I disagree, cppreference is pretty good. The information is very complete and useful examples abound. And just because you may not understand a template operator definition does not make it useless documentation.

consteval 2y ago
Yes 100%. I'll expand by saying I think there's two types of documentation: references and guides. cppreference is a really, really good reference. It's complete, highly specific, and well formatted. But it's an awful guide. If I was trying to learn C++ or it's standard lib, I would want to kill myself. The problem is these two types of documentation are almost perfectly perpendicular in my mind. Meaning, a good guide is a poor reference, and a good reference is a poor guide. Hand-holding step by step instructions, popular with many js frameworks now, are great guides. But when I want to know what function X returns and under what circumstances, I don't want to prune through a guide that starts at the beginning of the universe. And often those guides will be missing huge amounts of detail to lower the complexity. So you need one kind of documentation when you start, and then another 5 years later.

lifthrasiir 2y ago

In my experience all three you mentioned have their own excellent areas. MDN covers a vast range of subjects and knowledge levels but is most laborious to maintain and I have seen some gaps due to that. Rust is also similar in those aspects, but has different "documentations" that don't fully interconnect to each other yet. Rustdoc's automatic nature is great to have a complete and working documentation, but also means that API documentations are often weaker than those of MDN as the documentation should be embedded into the source code. Python has the same issues and also inconsistencies due to the lack of language-wide automatic documentation system (Sphinx autodoc is close but still annoying). Cppreference (perhaps not intentionally) covers only higher knowledge levels and absolutely standard matters. It is of course very clear that you can't really use cppreference for learning C++ from scratch, but it is well written as long as you fit with those assumptions and its writing quality is comparable to MDN in my opinion.

db48x 2y ago
Why does embedding the documentation into the source code make it weaker? The author can put as much or as little effort into the documentation as they want either way.
- lifthrasiir 2y ago
  A documentation is written for particular audiences, not always but typically users. And a user-directed documentation is largely a hindrance for whoever is actually updating a source code adjacent to that documentation, because it acts like a boilerplate template. An embedded documentation does make the absence of documentation obvious and helps towards the completeness, but not without a compromise. Ideally it should then be reordered and further elaborated externally so that it can be maximally useful. Rust has a good documentation but the general lack of such manipulation makes it often hard to navigate. For example `Vec` [1] has a lot of inherent methods with two separate orderings, where one is alphabetical in the sidebar and another is the declaration order, but none of them are actually logical and will benefit from reordering in general. Of course Rust folks are aware of this issue and have put a lengthy introduction with most important methods for each category, but that's less flexible and prone to future updates. [1] https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html

deleted 2y ago

[deleted]