4 ms·
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
by steveklabnik 7y ago
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.
- quietbritishjim 7y agoIt 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.
- steveklabnik 7y ago> I don't know if this is coincidence or deliberate It is conscious! This summary also shows up when you search, for example. > could be reformatted just by changing the documentation system. Yes. We've never had a bug report asking for this; I don't know how hard it would be, but it shouldn't be too tough.
- quietbritishjim 7y agoOne of the other comments linked to an issue (but it's understandable you don't know about it given that there are 10's of thousands!): https://github.com/rust-lang/rust/issues/40273 https://github.com/rust-lang/rust/issues/40273
- steveklabnik 7y agoHm, 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)
- quietbritishjim 7y agoAs 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.
- steveklabnik 7y agoHonestly, 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.
- jnordwick 7y ago> 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.
- steveklabnik 7y ago> 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.