Most of the crates out there don't provide high level documentation thus leaving some programmers like me scrabbing through examples and getting a headache trying to figure out how things work.
This is even true for large crates like egui, who rely on examples as a guide for newcomers.
I can give a more specific example with bevy: there are a lot of examples and documentation regarding basic stuff about the engine (ECS, materials etc...) but when you try to do something that is not what "a lot of people would do", which in my case was "computing with a compute shader and reading back arbitrary values to the cpu", you end up with nothing but a pull request from years ago that was never merged.
Learning from docs.rs is not really viable because of so many elements that are not useful on their own: I feel like the current rustdoc documentation system loses all the information regarding the context that an element belongs to.
Proposed solution
Given that writing documentation is knowingly hard and not fun, I propose two mechanisms with the idea of making "documentation writing" feel more like filling out a form (which might or might not even become an automatic habit, thus less energy-consuming).
1) Add, by default, some sections in each documentation entry (i.e. to every function / enum / struct / etc..) that are empty by default. I've thought of these two:
a "How to use"/"Snippet" or "Example" section where you write/copypaste a small snippet regarding the context in which a function/struct/macro/... is used
a "When do you use it?" section where you describe when to use that function/struct/macro/...
The first section would instantly provide the programmer with the intended use case of that specific element, thus giving insights on how that element is supposed to work inside the grand schemes of a crate.
The second section is pretty self-explanatory. I feel that by answering to the question of "When do you use this element?" you are providing a lot of high level insights regarding the use case of an element and it's context.
The fact that those two sections would be added by default would mean that documentations would be incomplete by default, with the designed intent of triggering the uttermost rage (jk) in a lot of programmers who will then be tricked into filling those gaps in order to get some dopamine
2) Automatically produce documentation entries or automatically produce a "documentation form"
in the first case, automatically add the sections to the in-source documentation. For example, automatically add these documentation lines:
given the ton of potential "bloat" that this would add to the source code file, another solution would be to split the rust documentation from the rust source code, which might actually be worth a new feature request on its own. I thought about some sort of C-header-like file, with only function / struct names and definitions:
<main.rs>
struct AnAmazingStruct {
int: yay,
int: yay2
}
impl AnAmazingStruct {
fn foo1(int a, int b) {
// ...*thousands of lines of code*...
}
}
<main.doc>
/// [Description]
/// Unwritten
/// [How to use]
/// Unwritten
/// [When to use]
/// Unwritten
struct AnAmazingStruct { int yay1, int yay2};
/// [Description]
/// Unwritten
/// [How to use]
/// Unwritten
/// [When to use]
/// Unwritten
AnAmazingStruct::foo1(int a, int b);
I don't think this is what would happen. Instead what would likely happen is that folks would just fill out those sections with a trivial sentence that doesn't actually help anyone.
I'm overall opposed to the general gist of this proposal. Partially because of what I just said, but also because having these sections on literally every item is almost certainly overkill. It's just not true that every single item in an API needs high level context spelled out for it. Here's an example IMO.
Hmm from I quick look I think that the documentation you pointed out actually fits into my description but I'm not sure; I'll get back to it as I find some time
I think generally it'd be better if there were more examples using the APIs in different ways, rather than trying to fit every possible use-case of every API in the docs for every single struct, enum, function, etc.
The PR was merged but bevy's documentation still doesn't contain examples, probably due to a bug.
I think that the rustdoc option is just a mitigation (a very nice one tho): developers will accidentally create documentation by writing some examples, but there's noone to complain if some areas of a library are not covered at all by examples.
I feel like providing examples of using an API in different ways has the same "vibes" as blacklisting dangerous patterns instead of whitelisting secure ones: developers will write examples for popular use cases and noone will cover for the not-so-popular stuff, while if you where to have an explicit "how to use" field foreach element then you're kind of certain that everything is covered.
Documentation already exists for each single struct/enum/function etc.. which is why I don't think that it would be that much of a problem; I'll now write an answer to burntsushi to address this issue tho
Hmmm I think you're right about this being overkill, but I only think that this is just because the method names literally spell out what they do, and they already have a "context" which is the Struct they are coming from.
You also pointed out a documentation which is astonishingly well-written, which I feel is an exception.
I'll still hold my view that something like this needs to be done, maybe for each element except for functions.
If folks where to just fill those sections with trivial sentences, then it would be bad practice which is completely different from people not writing them in the first place. Also, it might be the case that a trivial sentence is all that is needed to understand something.
In this case, there is literally nothing written: bevy - Buffer
Something as trivial as "When do you use it? - When you want to pass data to shaders" would be a great lead into further investigation
In the current state, documentations appears to be something "not-fun that people don't want to do". If these entries were a part of rust, then leaving them blank would be a problem that might be elevated to a clippy warning that you terribly want to get rid of, thus becoming some sort of problem-solving activity instead of a "I want to / I don't feel like writing documentation" problem.
I feel like the current system is too lax on how people write documentation, while rust is notorious for making programmers not do what they want to do, because what they want to do is bad.
That's exactly my point. That is not a rare scenario. It's a common one. Which is why I said forcing these sections into every item is horrendous overkill.
If you make something like this opt-in (as Clippy is), then I think you're more likely to find traction for an idea like this.
