Hacker News Reader

Good point, and for those unaware, cargo doc also shows you all of the traits defined for a type including those from other modules. You can even quickly see the source code defining the trait implementation. Rust has some of the best documentation of any language (which to be fair it really needs due to all of its quirks).

When someone accuses Java of being an IDE-only language, I guess I'll use this argument as well because Java also always had javadocs which would allow you to see all type hierarchies, inherited methods etc which make Java, similar to Rust, hard to read without an IDE.

What’s the easiest way to access the javadocs for the transitive dependency closure of your project? I didn’t know about cargo docs until now, but it seems way more useful than javadocs. An good IDE still seems better than both, however.

I believe Maven supports this, but I don't know if it's turnkey like cargo docs.

Something like mvn javadoc:javadoc -DincludeDependencySources=true perhaps?

Last time I looked at a javadoc there was no search field at all, to say nothing of a FAYT across your entire set of dependencies.

It has had search field for a decade or so.

I must have missed something but stdlib's javadoc is so horrendous. Yes it has exhaustive list of methods but it's devoid of actual programming content. No clear definition most of the time, no examples, no diagrams, no properties .. I swear on every remaining hair, everytime I have to visit these pages I go depressed. It was so much so that I wrote a json doclet to try to embed it into a repl to be able to experiment with actual objects with a bit of completion rather than having to waste precious time.

When Java appeared in 1995, my coding environment for it was XEmacs and Make.

Visual Age, JBuilder and Visual Café still took a while to come into being.

The other path that works well is to use Dash/Zeal for documentation.

I find dealing with a browser tab to be a bit awkward, especially if I'm working on a Rust project using Wasm and actively testing in a browser and having to flip between docs and my app. Having a dedicated documentation viewing app that I can show/hide with a keyboard shortcut just saves a second or so every time I need to pull up docs. And the integration with IDEs can sometimes mean I don't even have to leave my editor to get the answer I need. It also integrates documentation for std/core with docs for crates I'm using giving me a single search of everything that my Rust code can use. The only downside compared to cargo's docs is that it doesn't document my own code that I'm working on, but it's much easier to remember the details of that code.

The cherry on top is that it isn't limited to Rust. If I'm working on something with an FFI dependency, I can have the same documentation workflow for C/C++ documentation. If I'm working on a Wasm project, I can pull up HTML/CSS documentation the exact same way. All my documentation lives in the same place under the same keyboard shortcut.

Looks like Rust is missing something like hoogle. The language's types are barely powerful enough for it to add value, but it's certainly on the "adds value" side of the divide.

I think rustdoc supports a weak version of type-directed search.

I would agree.

rustdoc does support a hoogle-like syntax (in a rustdoc page click on the question mark next to the search field for shortcut and "search tricks"), sadly it's not very good.

Rust does add a few wrinkles due to its "type policy" being less regular though e.g. how you handle `self`, as well as the various types of references.

For instance let's say you have

    impl Foo {
        fn foo(&self, p: &Path) -> usize
    }

Does this match `Foo, Path -> usize` or `Path -> usize`? Or both? Or neither (because references). This also outlines a second issue which is whether `Deref` should be involved in the search (so e.g. should `PathBuf -> usize` find this).

Thank you for the thoughtful comment.

I'm actually aware of cargo doc - it's really useful, indeed. It's still note quite "greppability" though; I can open `cargo doc`. I can just open the browser and google "rust write_u16" and immediately find it. I can keep VS Code open with my project and search for it there. But neither of these is greppability :)

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.

Not only is that not relevant (that two commands have the same name doesn’t mean they have the same purpose), as far as I know you’ve managed to bring up “go doc” in a context where it is useless: if you give a symbol to `go doc`, it’s going to search that in the current package, which for the purpose of TFA is no more helpful than `grep`.

That go doc does not currently handle rust traits, a feature that has no equivalent in Go, is a pointless observation. Rust doc shows traits together with the class they are implemented for, so a “rust doc std::vec::Vec” should print them too.

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.

As far as I know you are, once again, completely wrong. `go doc` looks up symbols in a single package, which is the current package by default. That is what go doc's own documentation states.

If you had tried using it or otherwise knew what you were talking about you would know that you use it by specifying relative or absolute import paths for any package fetched with go mod or $GOPATH.

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.)

Thank you for once again proving the point which you keep missing: you have to give `go doc` a path to a module, which means you have to know where the symbol you’re looking up lives.

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.

TBH it's really hard to care about the "I need my docs to render in a terminal" use case.

What about "programmatic access to docs"? HTML pages aren't pipeable.

Honestly, I hadn't considered that (and I've upvoted) because I just use "search" in the rust docs. But I can see some value in grep'ability of docs, even if for me it has never really come up.

I suppose it would be nice if rust's docs supported a full text search.

What use case is that? FWIW, the docs are already generated programmatically in the first place, so you could access them with a similar approach (not sure how difficult that is, so maybe it's unrealistic advice).

Also there's a tool (forgot the name now) that can render them in the terminal similar to manpages.

If there is a terminal rendition tool, please share. Last I checked all efforts where abandoned, either due to too tight integration to rustdoc or due to bike shedding…

Note that there is no problem with the web version being available, it’s useful at times.

Sure they are, `cat x.html | rg -A 5 -B 5 ‘some string’`

It’s really hard to care about people who consider waiting for a webpage to build, a browser to load and a search to be typed as an acceptable solution to documentation access.

That argument doesn't work both ways. One group has far more stringent requirements than the other as evidenced by your use of the word "acceptable".

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’m sorry, what?

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.

Who said it has to be a "full web application"? Where are the orders of magnitude more work in parsing text and saving it as HTML files?

rustdoc, the tool being discussed, generates a full, interactive web application as documentation.

Plus, while one can dump plain text to HTML files it's still easier to just print the text.

If it were orders of magnitude less work to get the same results in a terminal that you get in a browser we wouldn't have browsers.

I'd love to know how you arrived at that conclusion, as it seems extremely illogical.

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.

That's how 99.99% of the population interacts with computers. They load a web page and then view it.

Fwiw people aren't building the webpage on demand. They're doing it on entry to the project, and so it's already ready when you want it.

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"

It is 2022, welcome to the future.

Yeah it sucks… :(

I guess it comes down to taste and preference, but I much prefer cargo doc to go doc. Go doc has a "brutalist/minumalist" approach (I understand some people prefer that), while cargo doc has a more "humanist" approach to the docs. I want all the bells and whistles in the browser docs like making it easy to search, read neatly formatted/rendered text, links, and syntax highlighting in the code snippets.

Edit: tpying is hard

Editor integration (LSP) is the way to go, gives you doc for the method or type inline in the editor.

> While the stdlib sadly remains out of it (long-standing RFC 2324[0]), cargo doc will otherwise generate the documentation including all dependencies by default.

It's probably mentioned in that issue, but I'm sure I read recently they want to crate-ise `std`; at which point presumably `cargo doc` would show it like anything else, wouldn't even know the difference? (That was even the motivation iirc, just for a different part of cargo, not doc.)

FWIW I personally think 5 possible matches is potentially already too much if you're a newcomer to a language or even just a large project. If you're willing to give up ad-hoc polymorphism (a big ask, but possible!) then in theory you don't even need to search outside your current file (given explicit import syntax, i.e. no wildcard imports).

But ad-hoc polymorphism is just oh so useful.

> FWIW I personally think 5 possible matches is potentially already too much if you're a newcomer to a language or even just a large project.

I'm... not sure what you'd want to happen when there are literally 5 methods called write_u16, how is a general-purpose search to know which one you're looking for without more information? If you want contextual matching... use an IDE (or hook rust-analyser into your editor of preference).

(also there are way more than 5 matches in total as there are methods like `write_u16_into` which would also match at a lower rank).

Without ad-hoc polymorphism and with explicit exports the correct one must have been disambiguated in import statements or must otherwise have been disambiguated at the call site via a namespace prefix (negating the need to do any searching at all).

So simple ctrl-f in the file would do (or the call site would identify it).

I've no idea what you're trying to say, but as far as I can interpret it when it comes to Rust you got things exactly backwards:

    foo().bar().baz()

if everything is monomorphic, there is no requirement that the result of bar() be a member of a direct dependency, to say nothing of being imported into the local scope.

If `baz()` is a member of a trait, however, that trait must be in-scope.

I'm talking about a hypothetical other language without ad-hoc polymorphism (in the spirit of the original article comparing Rust against other languages such as e.g. Go) and also in this case without methods. One poster child for this kind of programming is Elm (there are several other even more niche languages that do this as well).