3 ms·

I 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

by lacker 7y ago

I 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 ago
Rust’s standard library has no http support, so this post is a bit confusing to me.
- lacker 7y ago
  This 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 ago
    Yes, 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 ago
      Hmm. 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.
      - littlestymaar 7y ago
        The big issue here, is that you assume that you can get the same ultra-light Google search to give you the same answer for Go and Rust. That's a totally unrealistic expectations! If you google “nodejs http”, “PHP http”, “python http” or “Java http” you don't have the answer you're looking for either! “How to perform an http request in Rust” is a Google query that makes much more sense, and works for all the aforementioned languages.
        lacker 7y ago
        I disagree. Searching for [python http] works fine. Top result is this page: https://docs.python.org/3/library/http.client.html https://docs.python.org/3/library/http.client.html which explains precisely how to send http requests. Searching for [nodejs http] works fine as well. You get this page: https://nodejs.org/api/http.html https://nodejs.org/api/http.html Which does, in fact, give you a library that can make http requests. I won't dig into php and java because I'm not familiar enough with those languages to say what a decent way of sending http requests is. Finally, searching for [how to perform an http request in rust] does not work! It sends you to https://docs.rs/http/0.1.5/http/request/index.html https://docs.rs/http/0.1.5/http/request/index.html which is the same fundamentally broken library as you get with [rust http]. In conclusion, the Rust documentation is worse than any of Go, Python, or Node.
        steveklabnik 7y ago
        The second link for "rust http" for me (and in incognito mode) points to https://github.com/hyperium/hyper https://github.com/hyperium/hyper, which is exactly what you want.

by lacker 7y ago

steveklabnik 7y ago

Rust’s standard library has no http support, so this post is a bit confusing to me.

lacker 7y ago
This 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 ago
  Yes, 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 ago
    Hmm. 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.
    - littlestymaar 7y ago
      The big issue here, is that you assume that you can get the same ultra-light Google search to give you the same answer for Go and Rust. That's a totally unrealistic expectations! If you google “nodejs http”, “PHP http”, “python http” or “Java http” you don't have the answer you're looking for either! “How to perform an http request in Rust” is a Google query that makes much more sense, and works for all the aforementioned languages.
      - lacker 7y ago
        I disagree. Searching for [python http] works fine. Top result is this page: https://docs.python.org/3/library/http.client.html https://docs.python.org/3/library/http.client.html which explains precisely how to send http requests. Searching for [nodejs http] works fine as well. You get this page: https://nodejs.org/api/http.html https://nodejs.org/api/http.html Which does, in fact, give you a library that can make http requests. I won't dig into php and java because I'm not familiar enough with those languages to say what a decent way of sending http requests is. Finally, searching for [how to perform an http request in rust] does not work! It sends you to https://docs.rs/http/0.1.5/http/request/index.html https://docs.rs/http/0.1.5/http/request/index.html which is the same fundamentally broken library as you get with [rust http]. In conclusion, the Rust documentation is worse than any of Go, Python, or Node.
        steveklabnik 7y ago
        The second link for "rust http" for me (and in incognito mode) points to https://github.com/hyperium/hyper https://github.com/hyperium/hyper, which is exactly what you want.