I want to start by saying the author's right about wanting clarity in documentation and actually having documentation that's easy to navigate. golang, for example, has pretty good documentation, but whenever I visit the official docs I find it difficult to find my way to the information I'm looking for.
Having said that, it's worth asking if some of these asks are orthogonal to each other. For example:
>That page must contain (not link to) every method, and the descriptions of those methods, that can be called by that class, preferably including all inherited functions.
>That page must be as uncluttered as possible
"Including all inherited functions" is a pretty deep stack pretty quickly in a lot of languages. I'm entirely willing to acknowledge that maybe that means the page being "as uncluttered as possible" is to be read in the same vein as "the design should be as simple as possible, _and no simpler_".
>Seriously, cppreference straight up taking you to duckduckgo when using the search box is fucked.
In this case, we're seeing the tension between "The official docs should be great" and "I've mistaken a community project for the official docs" (cf. https://en.cppreference.com/w/Cppreference:FAQ the question "Who is behind this site?")
This sort of conversation naturally invites the more subtle conversations around who funds/maintains open/libre projects and whether those in the community who aren't actively working to improve the situation should follow ESR's wonderful advice, "Every good work of software starts by scratching a developer's personal itch."
> In this case, we're seeing the tension between "The official docs should be great" and "I've mistaken a community project for the official docs"
What official documentation? The standards? C and C++ are weird languages from a modern perspective, and that includes their cultures: They don't have a single blessed implementation, they have a standards body and a community. The standards body issues standards, the community does everything else. Both C and C++ come from a time when all "serious" languages worked like that. Yes, even BASIC. There's an ANSI standard for BASIC.
It would be great if the FSF and/or the LLVM people wrote documentation for C and C++ and it would be even better if they collaborated on it. But it would be no more "official" than cppreference is, because they don't write the standards.
I intend to sound like I'm agreeing with you here, not disagreeing.
The standard is what the committee publishes, yeah. For C++ it's https://www.iso.org/standard/79358.html ; I didn't look up the corresponding C one, but I have a friend (hi, Kate!) who maintains a C compiler who's pretty comfortable with the latest standard. The standard is the official documentation.
There's drawbacks having whitepaper standards that cost money, but this is what those languages have.
For what it's worth, it used to bug me that part of the standard is that there's intentionally undefined behaviour, but I went to BoostCon and heard some of the standard body talk and they impressed me as being thoughtful about leaving areas for implementers to innovate specific optimisations, so as not to restrict the potential of the community.
If I'm reading you right we agree that there's a difference between the standard and the implementation that's practical and real, but I'm not certain there's much to be done about that.
The C and C++ draft standards are publicly and freely available, and are generally better quality than the actual ISO standards. You can get the C standard here https://www9.open-std.org/JTC1/SC22/WG14/www/projects.html, and the C++ standard is also available in HTML form at https://eel.is/c++draft/ (having hyperlinks to individual sections is actually quite useful).
Having said that, it's worth asking if some of these asks are orthogonal to each other. For example:
>That page must contain (not link to) every method, and the descriptions of those methods, that can be called by that class, preferably including all inherited functions.
>That page must be as uncluttered as possible
"Including all inherited functions" is a pretty deep stack pretty quickly in a lot of languages. I'm entirely willing to acknowledge that maybe that means the page being "as uncluttered as possible" is to be read in the same vein as "the design should be as simple as possible, _and no simpler_".
>Seriously, cppreference straight up taking you to duckduckgo when using the search box is fucked.
In this case, we're seeing the tension between "The official docs should be great" and "I've mistaken a community project for the official docs" (cf. https://en.cppreference.com/w/Cppreference:FAQ the question "Who is behind this site?")
This sort of conversation naturally invites the more subtle conversations around who funds/maintains open/libre projects and whether those in the community who aren't actively working to improve the situation should follow ESR's wonderful advice, "Every good work of software starts by scratching a developer's personal itch."