Cargo doc is nowhere near as useful as something like go doc, where giving a symbol name immediately prints plain text documentation in the terminal. Cargo doc is just… inconvenient in comparison.
The point is that Rust is behind Go on convenient documentation access, which is ironic seeing that Rust requires documentation access much more than Go.
go doc also accesses all documentation for packages used in a project, making it do quite a lot more than grep.
Just in case this needs an ELI5: it queries project packages to print the relevant documentation for any accessible component: “go doc container/list.List” - bar any typos from a phone keyboard - prints all documentation for the stdlib linked list. In case Rust had a decent doc tool it would be the equivalent of “rust doc std::collections::LinkedList”.
(And no, that the Go tool needs to do less work to find all relevant documentation than a Rust equivalent is not relevant to the discussion.)
Which has nothing to do with the article, or my comments. The entire issue of the comment is that Eli has a symbol whose origin they don’t know. Where the symbol comes from is 75% of the question.
Of course if you want the documentation of a symbol whose full qualification you know `go doc` gives you that, that’s what I wrote above.
But it’s not TFA’s problem, and thus not the problem anyone’s trying to solve here.
Web documentation is easy to produce and is acceptable to many. All other kinds of documentation can also be converted into web documentation, therefore you do not have to spend extra effort for it.
Terminal documentation is more difficult due to the limitations of displaying things in the terminal, therefore it requires more effort.
I certainly agree that those who prefer terminals are a subset of developers - despite this missing the point of terminal-friendly documentation also means generally reusable and integration friendly, unlike a full web application - but terminal documentation is objectively orders of magnitude less work than writing web app for showing documentation.
Terminal documentation just means plan text. You print it, that’s it. Making it pretty involves indents and line wrapping. Any source formatting is just ignored.
Text based interfaces and terminal applications came first exactly because they are simpler than web browsers and applications.
We're not talking about a "TUI" app here - a terminal doc tool just dumps plaintext and terminates.
Plus, while one can dump plain text to HTML files it's still easier to just print the text.
Rust takes forever to build too if you've never built the project before, but most people also build that ahead of time too. Repeated doc usage and repeated builds/checks don't require the "full build"
Also there's a tool (forgot the name now) that can render them in the terminal similar to manpages.
Note that there is no problem with the web version being available, it’s useful at times.
I suppose it would be nice if rust's docs supported a full text search.
Edit: tpying is hard