4 ms·
> Anyway, comparing go documentation with rust docs, I'm surprised anyone can get any work done with rust. That's an unexpected comment. Rust has among the bes
by littlestymaar 7y ago
> Anyway, comparing go documentation with rust docs, I'm surprised anyone can get any work done with rust.
That's an unexpected comment. Rust has among the best documentation I've seen, and arguably the best ecosystem around documentation, which helps a lot and encourage third party developers to write high quality doc. I understand when people complain about the learning curve (like this article, because fighting the borrowchecker is only a thing while learning) but docs, really?
- mkr-hn 7y agoFor comparison: https://doc.rust-lang.org/std/fmt/index.html https://doc.rust-lang.org/std/fmt/index.html https://golang.org/pkg/fmt/ https://golang.org/pkg/fmt/ I don't know why I find Go's version easier to follow, but I do.
- setr 7y agoIn terms of content, they seem to be on par, and I think it's safe to say that's true for both stdlibs. Across the ecosystem (and particularly the third-party culture of documentation) is much more important; in my own experience playing with both languages, I tended to encounter more useless 1-line descriptions in golang than I did in Rust. Also golang struct descriptions always seem to be a bit lackluster.. But I can't point to any particular lib at the moment though.
- steveklabnik 7y agoContext: I wrote most of the stdlib docs the fmt docs are... not ideal. That said, there's a lot there, and it's all useful, but it's just tough. Frankly, I just punted on improving them, and haven't taken the time to do so in the years since.
- mkr-hn 7y agoIt seems like enough people find their way around them. Refinement might make them easier for people like me with less experience navigating language documentation, but that might come at the expense of developing the language. Priorities are important. Especially since Rust doesn't have Google's resources.
- littlestymaar 7y agoEven if it's not the author's favorite piece of doc, this is still a pretty good example of why I like rust docs. The rust version has : - syntax highlighting - a quick example of the feature
- lacker 7y agoI am not a fan of Rust’s documentation. To take one example: sending a HTTP request. There is tons of documentation of properties of the the HTTP classes built into the standard library, but it is extremely hard to find an example of working code. Wouldn’t a simple usage example of something like sending a single HTTP request be one of the most useful things to document? As far as I can tell, the best-documented approach is to use some external library and ignore the http support built into Rust.
- steveklabnik 7y agoRust’s standard library has no http support, so this post is a bit confusing to me.
- lacker 7y agoThis stuff, for example: https://docs.rs/http/0.1.19/http/request/index.html https://docs.rs/http/0.1.19/http/request/index.html "standard library" is probably not the correct term for this in Rust-world because it is under the "http" namespace rather than the "std" namespace. I just meant, "the stuff you use via typing `use http`".
- steveklabnik 7y agoYes, that is not the standard library, that’s a third party package. Its documentation does explain that it’s not a client or server.
- lacker 7y agoHmm. Its documentation doesn't explain that very well at all, to me. I am comparing the experiences of: 1/ Trying to do some http requests in go, searching for "golang http", and coming across the fairly well documented standard "net/http" library in go, at https://golang.org/pkg/net/http/ https://golang.org/pkg/net/http/ 2/ Trying to do some http requests in rust, searching for "rust http", and coming across this as the first result: https://docs.rs/http/0.1.19/http/ https://docs.rs/http/0.1.19/http/ which includes statements like "It's intended that this crate is the "standard library" for HTTP clients and servers without dictating any particular implementation." That's cool, I don't mind if no particular implementation is dictated to me. I just want to know how to use it by reading this documentation... but that never becomes possible. You could say the problem isn't that rust is documented poorly, the problem is that the standard library is missing some things that are in the standard library of other languages, and it's those third-party libraries that are documented poorly.