I really got annoyed by the Go package docs after I programmed in Go regularly for about a year. They were just so artless and flat. Each one is just a big list of all the stuff in the package, with no indication that the code has any structure to it at all. It was a few years ago though; perhaps it has gotten better?
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.
ecto and phoenix are shining examples of well written docs but its hardly the standard for elixir as a whole. many of the docs for most libraries are just lists of functions. some might have a short description though you're usually relying on a dialyzer definition at best.
Fair enough, but neither Ecto nor Phoenix are part of the stdlib, but being written by the some of core language maintainers with such a focus on documentation, they provide a great example for everybody to follow. Having excellent docs on the core libraries, the main SQL datamapper and web framework is the reason why Elixir is so loved even though it's quite a niche language.
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.
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.