I submitted a PR that hides use std::path::{Path, PathBuf} in code examples of the path module. Looking around, I see this practice is all over the documentation. I find adding such code noisy, given that it should be obvious that such imports are needed, just as it’s obvious that fn main() { ... } are needed, but omitted. I’ve seen this sort of practice in Python documentation, and think it’s a good idea.
Do you agree?
As an aside, I think we should have documentation policy for things like this.
I am generally in favor of removing main(), but not of use statements. However, I feel about a 5/10 on this opinion in terms of strength.
The key issue here is balancing readability with completeness. I don’t mind seeing use repeated, and it makes it easier to copy/paste. However, it’s possible that the repetition of use does harm readability.
I personally favour higher module/struct-level docs, in which case this would all be moot: you can have a full module/main setup in a longform example with no worries.
I would like to abolish headings in function & method docs, they are too noisy.
We could also experiment with having examples collapsed Into just one line that you can click to toggle. That might be a nice way to have them available if the reader is curious about how a function is used.
In general, I’d like to keep the use statements as long as they are not of things in the prelude. It’s a part of the documentation, it reminds the user what they need in scope to use it.
I don’t see how its helpful for every method on a type to have an import statement at the top of its docs, its just more words on the screen to filter out when trying to understand how the method works.
Seconded. They are more prominent than the actual method header, so they suggest structure at the wrong level.
Not to mention that the headings create HTML targets, but they are not scoped or uniquified, so that every "Examples" heading has the same id, and you can't link to it anyway.
If we have a link to a playpen that contains the imports, . Otherwise, we’d break the examples. There could also be an option to show them (perhaps a small toggle button on the code example to show/hide imports).
Wow, I just noticed that, yeah those are pretty useless examples. I agree with you on all counts. I think that function documentation is for some more complex functions, such as the various popular mem::* functions, and the like. *::new methods need not be exemplified, in my opinion.
I’m currently learning the language and the eco system and have to say, that missing imports is just enough mental strain to get me a bit frustrated sometimes. Of course this is more true for more complex examples, that import from multiple locations, e.g. in libraries, but for even more of novice, I could see, that even “obvious” imports are not that obvious sometimes. Also I self contained examples.
Would it be possible to have the imports only shown on demand, and derived from the example itself, so that it doesn’t clutter the sourcecode?
Personally I’m ok with a lot of examples as long as it does not break the flow.
I don’t think that too much examples is the problem. IMO, the problem is that example blocs are too big : even the tile of the block is far bigger than the name of the function.
I believe that :
subsection titles (failure, example,…) of the functions should not be in a font taller than the function title,
example block should be collapsible, and collapsed by default. If someone is interested by an example, he won’t be bothered by an extra clic.
The examples are tested before being merged, so they don't break, and playpen works fine with them. The noisy parts are just hidden by adding a # before the line, and are unhidden for the testing and playpen.
I think you fail to realise just how clueless [1] new users can be. We have enough trouble with people not grokking that you can't have statements outside function bodies, or thinking that try! doesn't work because "I copy+pasted the example code!". You have people who have problems whose solution is explicitly pointed out in the error message, but they just don't read it to notice.
Removing code that is required for an example to work is only going to make matters worse. The gain is... one line less in examples?
If there was some other way... like if examples very prominently indicated that they are abridged and are not complete as displayed, with some way of providing a full example without having to go to an external website, then I'd reconsider. As it stands, I can't accept this isn't a bad idea.
[1] This isn't intended as a "lol newbies r stoopid" comment; Rust seems to be attracting a lot of people whose body of experience and expectations are different enough that we need really good examples and documentation. You might find that extra line noisy, but to a beginner, that might be the line that helps them understand what's going on.
I’ve seen someone in IRC trying to use references when they don’t even know what the lifetime syntax is for. Not that they don’t understand lifetimes; they literally have never even seen the syntax; the word was totally alien to them.
I’ve directed people to the exact section of the book they needed, only to have them sit on their hands and do nothing until someone just gave them working code.
It is a damn miracle when someone actually expends effort to read documentation! We should seize that opportunity and make sure they have the best information we can reasonably provide if they do.
And anyway, as a non-beginner, let me tell you how I read the API docs: I collapse all the explanations and examples and just read the type signatures, until I find a likely method, then I expand just that one. I am in no way put out, bothered or hindered by one or two extra lines in an example. It’s completely irrelevant to me.
I just genuinely do not understand what the value proposition is with this change. It makes the docs objectively less useful to people who don’t know where to get the symbols involved, and doesn’t really impact anyone who does.
To expand on your comment, I might belong partially to this group, as I tend to learn a language from examples and the API documentation. Although e.g. the introduction section in the Python documentation is not bad, the API documentary has been much more helpful in my experience.
I think people have very different approaches to learn a new language, and it is best to cater to as many of them as possible.
This is exactly what I do too. (To the point that the docs would suit me better if everything was collapsed by default.) So count me in as another that thinks shaving off a line or two in examples is a strange value proposition. (Given the arguments I've seen so far---maybe there's one I'm not considering.)
I don’t see how its helpful for every method on a type to have an import statement at the top of its docs, its just more words on the screen to filter out when trying to understand how the method works.