I would go as far as to say that a non-negligible part of why people are intimidated by Rust is the rustdoc format and layout. Thankfully it makes up for it with an incredible Rust Book.
To me the gold standard of docs is Elixir followed by Racket. Even Go's docs are better than Rust, but that's mostly because of a much simpler type system, so simpler autogenerated docs for structs and their methods.
Scribble beats rustdoc hands–down when it comes to authoring documentation, but even with Rustdoc you can do a good job of it if you try (http://db48x.net/reposurgeon/rust-port-docs/reposurgeon/path...). I’ll have to check out Elixir next.
Here's an example of Elixir docs: https://hexdocs.pm/ecto/Ecto.html
Note the layout, the amount of prose to introduce a module and the function documentation that is not limited to just a quick line but often has multiple examples and tries quite hard to be clear and extensive.
There is no reason Rust docs couldn't be that good, but the example has to come from the top: improve the std docs, and everything will follow suit.
As a new Rust fan I would just love to have the std docs half as good as Elixir's. I constantly get lost in rustdoc.
I'm afraid, much Go code doesn't have that much structure. At least none that you could express in a machine readable form.
@tabular[#:sep @hspace[1]
(list (list @bold{Animal} @bold{Food})
(list "mouse" "cookie")
(list "moose" "muffin"))]
And the table of contents promises literate programming as well. Someone was really thinking when they put this together; I really like it.
The documentation generated for individual functions (such as <https://docs.racket-lang.org/scribble/base.html#(def._((lib....>) is fairly nice as well. Readable, linked together by hyperlinks on the type predicates as well as hyperlinks in the body of the documentation itself; it’s pretty good. Rustdoc puts links to the source code for each one though, and I would soon miss that.