Unintuitive behavior of the vast documentation library

[gdennie]

I am still a newbie to Rust and its ecosystem however so far my biggest struggle is navigating the documentation. The thing is, that specific cause has only come to light after some reflection and confidence in my understanding of things. I expect others are stumbling through the documentation structure equally oblivious. The issues are three...

1. As a strongly type language it should be convenient to locate a type or trait and all its related methods. Often these require and produce additional types and traits. It should be possible to follow a trail through the documentation as links between such various declarations per the nature of HTML. Unfortunately, that is not the browser experience which is a massively missed opportunity.

2. docs.rs allows for the selection of other documentation libraries. However, it erases the browser link history when that is done such that you cannot simply "backspace" to return to docs.rs. That was a surprising behaviour. As a result, docs.rs does not function a root in a hierarchy but merely as a one way door.

3. Finally and surprisingly, the documentation for the standard library is separate from that for crates.io. This separation is annoying since the distinction is nonsensical. The correct delineation is between the language syntax and the libraries (types, methods, modules, etc.) produces and uses. Granted, there are library features that some language syntax depend on but their documentation may be duplicated in the syntax description or pointed via a link into the library documentation. For instance, for over Iter, ? returning Result or Option, etc.

[Nemo157]

However, it erases the browser link history when that is done such that you cannot simply "backspace" to return to docs.rs.

Could you give an example of where you see this? That's not the behavior I see and would be considered a bug.

the documentation for the standard library is separate from that for crates.io. This separation is annoying since the distinction is nonsensical.

Are there any negative effects from this documentation being on a separate site? All docs on docs.rs should be automatically linked through, and since std doesn't (publicly) depend on crates.io crates there can be no reverse links.

[Nemo157]

Whoops, missed point 1

It should be possible to follow a trail through the documentation as links between such various declarations per the nature of HTML.

This should work in the vast majority of cases, items in the rustdoc generated details should all interlink automatically. In the prose sections developers can (and generally do) use intra-doc-links.

There are bugs with these (e.g. #1588), but those should be fixable if someone will put in the work.

[gdennie]

I am using Firefox on Linux Munit

1. The function of interlinking now seems to work fully.
2. The subsite selection from https::/docs.rs now creates a separate tab for each subsite, which is fine.
3. The library separation is less of an issue with the interlinking now working. The need to search two repositories is somewhat less of a nuisance.

Thanks for your quick response.