5 ms·
> "Interesting", you think, "I didn't know that Vec has a write_u16 method". You quickly check the documentation - indeed, it doesn't! So where is it coming fro
by masklinn 5y ago
> "Interesting", you think, "I didn't know that Vec has a write_u16 method". You quickly check the documentation - indeed, it doesn't! So where is it coming from? You grep the project... nothing. It's nowhere in the imports. You examine the imports one by one
> [...]
> It's entirely possible that using a language like Rust without a sophisticated IDE is madness, and I'm somewhat stuck in the past. But I have to say, I do lament the loss of greppability.
Seems more like Eli has completely missed an important and integral feature of the rust ecosystem: `cargo doc`.
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.
This means you can in fact get this information by "checking the documentation", just the right one: a global search in the project's `cargo doc` will quickly tell you where the method comes from[1], without the need for any IDE or complicated integration (though I don't think it works with text browsers as it uses javascript, for terminal / console contexts maybe try `rusty-man`, I don't know how good it is tho).
I couldn't imagine working on a Rust project without having its `cargo doc` permanently open in a tab, having the unified offline documentation for all your dependencies is just way too useful, I run `cargo doc` almost as often as I run `cargo check` (despite that being mostly useless for binary crates...)
[0] https://github.com/rust-lang/rfcs/issues/2324 https://github.com/rust-lang/rfcs/issues/2324
[1] just tried it on a local project, the first methods it surfaces are 4 methods from byteorder (on ByteOrder, WriteBytesEx, BigEndian, and LittleEndian) and one from serde_json (on Formatter).
- arghwhat 5y agoCargo 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.
- slaymaker1907 5y agoGood 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).
- curun1r 5y agoThe 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.
- brabel 5y agoWhen 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.
- halpert 5y agoWhat’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.
- jolux 5y agoI believe Maven supports this, but I don't know if it's turnkey like cargo docs.
- TravelPiglet 5y agoSomething like mvn javadoc:javadoc -DincludeDependencySources=true perhaps?
- masklinn 5y agoLast 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.
- brabel 5y agoIt has had search field for a decade or so.
- agumonkey 5y agoI 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.
- marcosdumay 5y agoLooks 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.
- Ar-Curunir 5y agoI think rustdoc supports a weak version of type-directed search.
- masklinn 5y agoI 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).
- OJFord 5y ago> 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.)
- dwohnitmok 5y agoFWIW 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.
- masklinn 5y ago> 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).
- dwohnitmok 5y agoWithout 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).
- masklinn 5y agoI'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.
- dwohnitmok 5y ago
- eliben 5y agoThank 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 :)