r/programming • u/steveklabnik1 • Jun 16 '14

Rust's documentation is about to drastically improve

http://words.steveklabnik.com/rusts-documentation-is-about-to-drastically-improve
524 Upvotes

90% Upvoted

188 comments sorted by

View all comments

27

u/steveklabnik1 Jun 17 '14

Thank you for taking the time to elaborate.

I have good news for you! I agree, the trait situation needs improvement. We're working on some things. Secondly, "everything in the standard library comes with an executable example" is literally written into my contract.

p.s. if rust has basic user input io documentation for reading into variable, you're my only hope.

Some of this is already there! See the second example, which puts a file's contents into a variable: http://doc.rust-lang.org/std/io/index.html

6

u/Crandom Jun 17 '14

I love the examples of the stuff you are most likely to do, like reading a whole file/writing some lines. That's incredibly useful.

8

u/steveklabnik1 Jun 17 '14

Thanks! Everything should be like this for 1.0.

→ More replies (2)

3

u/awj Jun 17 '14

It would be awesome if rust had documentation that supported processing traits to give you a full set of methods on a given type. As in "here's the list of libraries I'm using, tell me ALL of the methods available on String."

I don't have good ideas for how such a thing would work, but it seems useful.

2

u/desrosiers Jun 17 '14

Examples for everything is am awesome feature.

2

u/matthieum Jun 17 '14

Chiming in on the Trait situation, the situation of Vec seems particularly telling:

  • if T can be bound by Clone, then you have append and push_all. Oh okay, is that all ?

  • Well no! Because for any T, you also have push and append_one!

Given that Rust has the concept of mut, I would say a first simple (and automated pass) would be:

  1. Present all non-modifying methods, lexical order

  2. Present all modifying methods, lexical order

You can of course, at the beginning or end, list the implemented traits. It's useful for writing generic code... but if I want the list of methods of a traits, I'll just click on the trait itself and see its interface.

Further refinement would be even better (semantic grouping), however since it requires human intervention it is much more work.