Document trait impl behavior

[apasel422]

All implementations of (at least) the following traits should specify their exact behavior using a doc comment on the appropriate impl methods:

• Default -- exactly how the collection is constructed (e.g. by delegating to some other method)
• Extend -- whether the new elements are inserted in the same order they are yielded from the iterator, and, for maps and sets, what happens in the case that there are duplicates (including what it means for there to be a duplicate)
• FromIterator -- same requirements as Default and Extend
• {PartialEq, Eq} -- what constitutes the equivalence relation
• {PartialOrd, Ord} -- what constitutes the partial/total order

Additionally, all types implementing Iterator should document their ordering invariants (including the case in which there are none).

[Gankra]

Default, Extend, and FromIterator all seem obvious? Default is sugar for new, and Extend and FromIterator are sugar for the simplest insertion.

Eq and Ord, I guess are a bit nontrivial...

[apasel422]

Hmm, I guess those three are normally obvious, but {Eq, Ord} seem important to specify, especially because it's so easy to silently break code that is using them.