Document order guarantees for combinations

[ryanavella]

Fixes #819 by documenting the order guarantees for Itertools adapters.

[Philippe-Cholet]

CI failed because rustfmt does not accept trailing spaces.

The question is if we want this guarantee to be library wide or limited to some adaptors like Combinations. I'll let @jswrenn decide on that.

[ryanavella]

The question is if we want this guarantee to be library wide or limited to some adaptors like Combinations. I'll let @jswrenn decide on that.

Ah yes, I hope I didn't misunderstand the conclusion from the other issue. I originally wanted a guarantee for Combination-like adapters, but I interpreted your comments as saying we don't intend to break iteration order for any adapters.

I could add a blanket "unless otherwise noted" clause, if there are specific adapters we'd like to leave open to further optimizations?

[jswrenn]

Sorry for the misunderstanding. I don't think we can guarantee order for all adaptors, but I am okay guaranteeing it for the combinations adaptors.

[ryanavella]

Thank you for the clarification, I've updated this PR so that the guarantee is only shown under Itertools::combinations and Itertools::tuple_combinations. Let me know if all looks good to you.

[Philippe-Cholet]

@jswrenn What do you think of his formulation?

[jswrenn]

Whoops, I had a draft review I thought I had posted. Thanks for the ping. It's just some minor nits.

[Philippe-Cholet]

@ryanavella If you could commit jswrenn' suggestions and squash into a single commit, I would gladly merge this.

EDIT: Done.

[Philippe-Cholet]

@jswrenn My approval is not enough to get this merged.