Yes, the cop page probably has some bespoke work on the page, but it still demonstrates ideas that are partially auto generated (and most of that page is auto generated).
* the method and functions aren't sectioned in any useful way. Just a list of functions (solved by adding section and subsection to the doc comments). Methods that create, search, mutate, test, transform, etc should be sectioned off.
* no use of alignment, just blobs of text
* poor use of color. Both java and cpp use color to break up sections and alignment to distinguish different parts of the signature. Rust is just a page of text that is very difficult to scan.
* no summary. Cpp summarizes the group of method before clicking b through to individual listings, while java summarizes each method at the top. This is useful for searching in a page. Rust is once again just a block of text.
* rust also has a unique issue in how to organize traits and other rust specific constructs. It really should have figured this out by now.
I can keep going on the uselessness of the rust docs, and I say this as someone who was involved in the language in the past, and give it a new shot about once a year. But the docs have always sucked compared to other languages.
Maybe it's just what you're used to, but I massively prefer the Rust docs for `String` you linked to Java or C++'s.
I think largely for one reason: the sidebar! I just scroll the sidebar for the method I know I want or a method that sounds like what I'm hoping to find, and then click it.
Java & C++ both lack that, it doesn't matter so much with the latter because the page is pretty short, but Java's is huge, and to me totally unnavigable.
Old Java doc (as generated by the original javadoc tool which also inspired other languages I believe) had the kind of navigation you're looking for - it was a boxy HTML frame-based layout so it had to go, but I'm not sure why the default javadoc theme dropped in-page method navigation altogether.
So, I disagree that it "sucks," but what I will say is this: rustdoc has basically been maintained by one or two people over the last ~5 years. It is very hard to contribute to, because it has to use the compiler itself to actually generate the documentation. This means that changing it means changing the compiler, which means a long development cycle. Additionally, this also means working on it isn't really like working on a normal web app. We've tried to get folks to contribute, but they all bounce off. So this means that any improvements we would like to do are really difficult, and there's not a lot of help.
I am hoping that the rust-analyzer work lets us completely fix this, in the same way I was hoping the rls would before, but it's just not ready yet.
> This means that changing it means changing the compiler,
Wow. What a terrible decision. I'm quite surprised that people actually agreed to that.
I originally said it was shit but I toned it down a little. The information isn't bad, just too difficult to find if you don't already know exactly what you are looking for. You work on rust core so I don't think you are the best person to judge.
The good part is this can mostly be solved by better formatting and adding a top one-one summary section that groups similar functions and traits (creation, mutation, lookup, etc). With just that you could even convince me to ignore the terrible formatting in the lower section.
The general take away is that the docs are too difficult to scan and if you don't already know something exists and its name, the docs aren't very useful.
> Wow. What a terrible decision. I'm quite surprised that people actually agreed to that.
It's not really possible in any other way. Building API docs is a compilation process, from source code to HTML. You either use the compiler, or re-implement parts of it. The latter makes for interesting bug possibilities.
It seems like there is some low-hanging fruit that addresses one of the main complaints of the parent commenter (which I agree with). It would be nice if there was a list of all the methods with just a one line summary of each - like the sidebar but with fractionally more information.
I'm thinking in terms of Doxygen's brief comments vs detailed comments here. Pages typically go (1) class brief comment, (2) list of methods with their brief comments, (3) class detailed comments (including examples), (4) method signatures and detailed comments (linked to from above). Doxygen has many serious problems but I think it gets this bit right.
But a quick glance at the linked std::string::String page suggest that the first sentence of each method's docs already works as a brief summary of its function. I don't know if this is coincidence or deliberate, but if it is deliberate then the page could be reformatted just by changing the documentation system. I'm not saying that's easy, but it's less work than having to add something to every individual function.
Hm, I think that I understand this issue to be something different than what the parent is asking for, but maybe I misunderstand one or the other! (As you can see, I commented in that issue, hehe)
As yes, so you did! Hmm, partly I think I had this in my head before I even read the root comment, but I think I was looking at this point in it:
> no summary. Cpp summarizes the group of method before clicking b through to individual listings, while java summarizes each method at the top.
When they say "java summarizes each method at the top." I think they're talking about the fact that the Java page has one line for each method with the brief description next to it. The C++ one is a bit mixed up with the fact the methods are also grouped together (by overloaded name), but they already mentioned that in their first bullet point so I think they're just referring to the brief text descriptions here.
Honestly, like a lot of rustdoc bug reports, it isn't really super clear what exactly it's tracking. Someone suggested one thing, then some related things were suggested... it's tough.
>no summary. Cpp summarizes the group of method before clicking b through to individual listings, while java summarizes each method at the top. This is useful for searching in a page. Rust is once again just a block of text.
It looks like Rust docs webpages default to expanded view instead of collapsed view. You can press [-][+] in the upper right hand corner to get a more summarized view that looks more like the cppreference example. Example video :
I'm kind of intrigued how widely opinions differ here. I consider the Rust docs here dramatically better due to their focus on soft documentation. I can't stand Java docs.
Not even a useful softdoc though. Let's say I need to search then mutate an data structure. There are probably number of ways to do what I need. Right now, it is almost impossible to see what my options are.
And I'm not going to memorize the API either. Sorry.
I personally prefer Rust's style here to Java, and a good deal over C++.
I had to learn Java last year and--even as an experienced programmer--the guides we're pretty miserable. The info was there and it was terse [1], but I wound up paying for a course elsewhere because the official docs weren't working for me.
Rust method here of combining the guide (Struct docs) and reference (Methods) is vastly superior, in my opinion. One niggle I always have with docs is that the two things are considered separate and I have do figure out which link is the one I'm looking for. God help me every time I need to find the String functions in the Python docs.
If you don't like looking at the guide in the Rust docs, click the "[-]" in the upper right. It'll collapse everything in the page and make it look a lot more like the C++ sample.
It is way too difficult to find a function you don't know exists, and I'm not going memorize the api.
It doesn't even come remotely close to the CPU docs. It isn't sectioned just a dumb list of methods where similar methods can be pages away from each other (eg all the methods to look up or index into a data structure should be grouped).
Maybe I just have a higher standard than most rust users.
I (and i'd assume many others) am not interested in pulling up references AND guides to figure out what I want. Rust has a 1 stop shop that not only tells me WHAT I can do but HOW with examples. Javadocs is horrible in that I see a method I want to use and then have to google for an example on how it is used. Rust >>>>>>>>>>>> Java in this regard.
Thats a bit harsh. Yes, the documentation might be (is) a bit hard to read in a sense that its hard to _find_ something from it, but otherwise I've found if quite complete (when it comes to the standard library). Most (if not all) of your points are about the readability of the rendered documentation and not the documentation (content) it self.
Immediately, I see what other methods are relevant in this same context. So many languages references are simply enumerations of items in the library, but they don't provide the context needed to actually gain proficiency in the tool and learn incrementally.
I wouldn't call them useless though, clicking the [-] collapses all comments and gives a somewhat useful overview of what's available. It's far from ideal, but still useful.
And your post doesn't even mention that many of crates, even important ones like crypto, aren't even fully documented and it's very common to just hit the wall of missing entries and no over-arching manual on how the crate should be used.
> rust also has a unique issue in how to organize traits and other rust specific constructs.
A thousand times this. It doesn't matter how well written and organized that page is, because it's completely irrelevant. The relevant information is all on the traits documentation and other libraries.
I agree that the way traits are organized in rustdoc could be improved. It's often hard to find what the capabilities are of a given type because of what we'd call the "yo-yo problem" in OOP: you have to click through multiple levels of the hierarchy to find what you're looking for.
Compare the string pages.
Rust: https://doc.rust-lang.org/std/string/struct.String.html
Java: https://docs.oracle.com/en/java/javase/11/docs/api/java.base...
C++: https://en.cppreference.com/w/cpp/string/basic_string
Yes, the cop page probably has some bespoke work on the page, but it still demonstrates ideas that are partially auto generated (and most of that page is auto generated).
* the method and functions aren't sectioned in any useful way. Just a list of functions (solved by adding section and subsection to the doc comments). Methods that create, search, mutate, test, transform, etc should be sectioned off.
* no use of alignment, just blobs of text
* poor use of color. Both java and cpp use color to break up sections and alignment to distinguish different parts of the signature. Rust is just a page of text that is very difficult to scan.
* no summary. Cpp summarizes the group of method before clicking b through to individual listings, while java summarizes each method at the top. This is useful for searching in a page. Rust is once again just a block of text.
* rust also has a unique issue in how to organize traits and other rust specific constructs. It really should have figured this out by now.
I can keep going on the uselessness of the rust docs, and I say this as someone who was involved in the language in the past, and give it a new shot about once a year. But the docs have always sucked compared to other languages.