> The documentation is hands down one of the best language documentations I’ve ever seen.
I take you haven't looked much at documentation of other languages. For
example, how to read a single text line from a TCP socket? Where do I need to
look in the docs, starting with TcpStream struct?
Some areas of the standard library still aren't great; I'm working on it.
In this case, https://doc.rust-lang.org/stable/std/net/struct.TcpStream.ht... has an example of using `read`, but it's not a line. If you type "line" in the search box above, the third result looks relevant: std::io::Lines. Which links you to BufRead::lines. The general docs for BufRead state "If you have something that implements Read, you can use the BufReader type to turn it into a BufRead." So boom, wrap it in a BufReader, call lines, then call next. Done.
I wrote that out to just to see for myself; we have more work to do! Always more work to do...
> Some areas of the standard library still aren't great; I'm working on it.
Oh, I don't doubt it. I'm not even saying that the Rust's documentation is
bad. I only object to the claim that it's one of the best (because I've used
better ones). It simply needs more work to reach that state, as you seem to be
perfectly aware.
> [...] So boom, wrap it in a BufReader, call lines, then call next. Done.
From my perspective, this is a non-obvious process. I couldn't find the
solution on my own, and I'm not a newbie in reading documentation, as I have
a habit of reading reference docs, which historically included learning most
of Perl (which is not known for being simple) and, more recently, much of
Erlang (which has documentation that needs proficiency in reading it).
To give some constructive feedback, put some thought to how can one discover
from the documentation all the traits applicable to the situation (possibly
avoiding using the search box, which I usually don't expect to provide precise
results). If there was some connection from TcpStream to BufReader,
I wouldn't have any problem with finding the latter.
Totally! std::net is an area I haven't touched at all. Whatever's there is the accumulation of whoever decided to write some things, no systematic work was really done to document it yet.
I actually sort of expected the documentation to be generated, not completely
hand-written (mainly because I'm a fan of JavaDoc descendants, if they are
used correctly). If this was the case, then the doc build tool would need to
extract and present some additional information about the applicable traits.
I take you haven't looked much at documentation of other languages. For example, how to read a single text line from a TCP socket? Where do I need to look in the docs, starting with TcpStream struct?