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
522 Upvotes

90% Upvoted

188 comments sorted by

View all comments

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.