
Thoughts about Rust in 2017 - anonyfox
https://medium.com/@Hisako1337/rust-in-2017-8f2b57a67d9b#.g50x9mmst
======
dozzie
> 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?

~~~
steveklabnik
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...](https://doc.rust-
lang.org/stable/std/net/struct.TcpStream.html) 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...

~~~
dozzie
> 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.

~~~
steveklabnik
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.

~~~
dozzie
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.

~~~
steveklabnik
The type signatures are generated, but the text and examples come from
extracting documentation comments.

~~~
dozzie
So I was right, it's a generated thing (obviously, a tool cannot provide the
description nor usage examples).

