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.
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.
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.
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.
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.
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.
> 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.