Small tweaks and ideas that i think may improve docs.rs

as i rust new comer, i find that docs.rs is one of the most, and efficient api documentation out there. there are a list of tweaks and ideas that i believe once added they may improve accessibility and may help beginners like me better use docs.rs and decrease the number of time we switch between tabs, which is quite anoying to be honest.

Simple and easy to implement

a button to copy crate version

i find my self many times in a crate doc, and i need to copy its version, so i need to switch crates.io locate the library and copy the version, as a beginner i find this to be very annoying

a page that index api required by a feature

its not clear when i browse an api, what feature should be enabled, and its painful, because i need to use eather google and if i am lucky ill find it, or try to look for hints, it could be helpful if the feature required by the api is under its declaration, or just a page that indexes all the api and there features, i prefer the first one.

improve search

the search as is (fuzzy) is good, but not enough, sometimes i want to search for exact word, but i don't know how i should do it. for now i clone the repo, and using vim+fzf i search for the exact api name, but it could be good if its builtin in docs.rs

Probably difficult and requires time

history of navigation

when i am browsing api, i tend to click so i can follow the return type, some times the return types are deep, it will be helpful if there is a sidebar, that keep track of the history of clicks, so once i reach a level deep, i can click on any parent and go back to it.

tree

this one is probably more difticult to implement, but imagine if we could have a page like the introduction page that contains a tree representation of all the api in the crate, which one called which, and you can simply click on the one we want and go to it, or even better, the tree will filtered down by a search key, that will leave only the path that contains the result of the search key, i have many ideas about this tree, but i am sure it will make rust developers easier, especially if a developer can see the whole picture instead of keeping track of api in a notepad, or a papier and pencil like i do.

i am not talking about the uml representation, simply using the data already exist, api -> return type because i guess (at least for me) these are the most important piece of information i need when using a crate, so if they are easily accessible, they can help making sense of the crate

Regarding figuring out which feature is required for each api, there is ongoing work on something like this, and you can see it in action on e.g. the documentation for tokio.

@alice this morning i needed to use AsyncWriteExt on tokio, first thing i needed was TcpStream::write so on the doc, i only found there AsyncWrite i did import it, but write did not work, so i kept search then i found AsyncWriteExt i did import, but still not working, on the introduction page, there is a list of feature, but its not clear for what api do i need it, what i did is guessing, since AsyncWriteExt is on tokio::io probably i need io-something, the hint that tokio include in the introduction page io-util: Enables the IO based Ext traits. was helpful, because it does indicate Ext in it, but what about when a crate does not include a hint. should i enable features one by one, tell i find the one needed? or enable them all, that sounds good tho, considering the pain to find the right feature. how do i know a feature is even required? digging through the api is hard, probably not that hard when its done once or twice a day, or once you get used to a crate and its requirement, but its really hard for a new comer like me, because its not just one crate its many crates, and once these little action adds up, then it become hard, and sometime i just create an impl to do what i want because its easier than figuring out how a crate work, i took this action this morning when i was trying to use chrono to print the current time, i know probably its easy to do, all i want is the current time in this format Y-m-d H:i:s\Z and i saw Utc and as_rfc* but i was too overwhelmed with search to keep digging and figuring it out, and i noticed that all i need is a simple math and std::time::{ Instant, Duration } to build what i need. why is it this hard? is it just me? it feels like a barrier everytime i want to use a crate. and i believe that it can be broken once simple tweaks that expose just the right peice of information needed.

one of the things i see, is that the docs are structured in a way that behaves like people knows there way arround, i am sure that if i built a crate and i generated the docs for it, it will feel just right, because its my crate and my api. but not for the others.

It's quite hard to reply exhaustively to that, but here are a few pointers:

Extension traits such as AsyncReadExt can be a bit difficult to find, yes. This is why we make a link to it on the doc for AsyncRead, and additionally you would stumble upon it if you search for a method that happens to lie on this trait.

The specific feature needed to use the trait is io-util, and this is listed on both the trait itself and every function on the trait in a blue box.

There are also some general tricks for finding things that are the same on all Rust crates: The Trait Implementations section near the bottom of the documentation of a type is always a good place to look for special things you can do with it. E.g. for tokio::fs::File, the section lists that a file implements both AsyncRead, AsyncWrite and AsyncSeek, and now you can go look those up.

Similarly traits have a list of types that implement the trait. Of course, things like this can be hard to know to look for, but at least it's the same in all crates.

1 Like

Easier copying of versions to copy'n'paste is a "faster horse" solution. The real one is:

cargo install cargo-edit

and never copy'n'paste crate version ever again. This will be built into cargo eventually.

(I agree with other points tho)

2 Likes

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.