I am in the process of making docs for my first project. And by seeing the empty docs with only the function signatures. I realized how much easier it is to skim through the docs and find what you are looking for if the function text is collapsed by default.
Another idea for the same thing would be to include functions signatures in the sidebar somehow for easy access. But this requires a lot more work than just collapsing by default.
If none of the above is accepted, could there at least be a quick collapse / expand button that collapses all the function information at once. I find myself sometimes collapsing all the functions one by one to have a better overview…
This is a common complaint, but it’s not clear what the right thing to do is yet.
Changing the sidebar to be more useful is a clear win and I think somebody should do.
The text is useful for people who don’t know what they are looking for. I’d like to hear some more radical designs to solve this problem rather than just changing the expandedness of the current design.
There is a button that collapses the entire page at once in the top right.
Amazing! That will save me a lot of time. It's not very clear though that it collapses the whole page. I would have never known without you pointing that out
Agreed, but it's tricky. Because big redesigns demand quite a lot of effort and require both programmers and designers to work together.
If I can suggest anything, I would open a sticky thread (if it doesn't already exist) where designers could post mock-up's for all web-based services. Mainly Rusdoc and Crates.io. The core team could then take their time to review the mock-ups. The community could give feedback. The designers could improve their mock-up based on the critique. And when the Core team feels like they have a strong design they could start to implement it.
This would give a centralized place for all design discussions until the big redesigns actually happen.
Another thing I’d like to see is some indicator (maybe in the sidebar, as a fixed thing that scrolls along) that shows, to which trait do the methods shown belong. If there are tons of traits and they have tons of methods that each have many paragraphs of text and examples (the String API is an obvious example), you easily lost sense of the big picture.
I used to cmd-F inside the page to try and find relevant functions, but after finding what I was searching for, I had to scroll a bunch to learn what trait I had to import to use the methods.
I don’t have any concrete design proposal, just stating the problem. But maybe it would help if the trait subheader simply scrolled along or something…?
Another thing that’s slightly distracting: the method signatures, although they are semantically like headers, are smaller and weaker-looking than the subheaders such as “Examples” and “Panics”. That makes the API docs look visually quite noisy.
Add [src] links next to each method, and more importantly next to each impl listed for a trait: implementations of a trait are often not in the same file as the trait itself, so it can be hard to find the file that contains it.
Similarly, when clicking on the item, instead of just highlighting and scrolling to it (somewhat useless, since you must already be scrolled to it to click on it!) expand it and collapse everything else.
Yes I think subheadings in function & method documentation are only distracting, they don’t work. In your own crate docs, you can modify the css though, or you can just not use headings.
