3 ms·

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

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.

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 ago
  One 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 ago
    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)
    - quietbritishjim 7y ago
      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.
      - steveklabnik 7y ago
        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.

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 ago
One 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 ago
  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)
  - quietbritishjim 7y ago
    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.
    - steveklabnik 7y ago
      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.