5 ms·
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
by arghwhat 5y ago
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.
- masklinn 5y agoNot 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`.
- arghwhat 5y agoThat 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.
- masklinn 5y agoAs 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.
- arghwhat 5y agoIf 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.)
- masklinn 5y agoThank 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.
- staticassertion 5y agoTBH it's really hard to care about the "I need my docs to render in a terminal" use case.
- edflsafoiewq 5y agoWhat about "programmatic access to docs"? HTML pages aren't pipeable.
- staticassertion 5y agoHonestly, 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.
- spoiler 5y agoWhat 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.
- arghwhat 5y agoIf 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.
- bogeholm 5y agoSure they are, `cat x.html | rg -A 5 -B 5 ‘some string’`
- arghwhat 5y agoIt’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.
- spoiler 5y agoI 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
- kzrdude 5y agoEditor integration (LSP) is the way to go, gives you doc for the method or type inline in the editor.