Hacker News Reader

Comment by bobajeff | Hacker News Reader

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.

View on HN

> 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.

A good alternative to cppreference is https://devdocs.io/cpp

Same content, better search.

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.

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.

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

I’m not so sure that the order of methods matters very much in most cases. In Rust you can at least present them in any order you like, or you can use the module or trait documentation to explain how the order matters.

C++'s canonical reference is a very thick book. I figure there is a conflict of interest between the published version and presenting an equivalent online.

It's worth noting there is no good C documentation in one place, either.

Python dumped the book quickly and went online, but that was probably more for the publisher not being interested in releasing new versions every time something changed. It's also a little younger, but still appeared before the widespread use of broadband internet.

I think Perl was probably the first one to make documentation a real first class citizen, with perhaps Emacs shining a light in that direction.

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.

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.

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.

Reply on news.ycombinator.com