the actual helpful docs for std::cmp is under std::cmp::Ordering

[deepak]

rust noob here, looked up rustdoc for std::cmp
and realised that the meat of the docs and examples are under std::cmp::Ordering

should it be brought up from std::cmp::Ordering to std::cmp ?

[GuillaumeGomez]

std::cmp is a module whereas std::cmp::Ordering is an enum. It seems more logical to have specific examples on a type and more global ones (or just a global explanation) in the parent module.

[steveklabnik]

part of #29329

[nodakai]

@GuillaumeGomez Trying to be "logical" sounds nice except your argument is not.

Given that either the Ordering enum or the PartialOrd trait alone cannot implement user-defined ordering, we can "logically" say the meat of the documents should not belong to either of them.

[frewsxcv]

and realised that the meat of the docs and examples are under std::cmp::Ordering

In particular, which sections of std::cmp::Ordering did you wish were in std::cmp? The docs for std::cmp::Ordering look pretty bare right now.

[deepak]

in particular, which sections of std::cmp::Ordering did you wish were in std::cmp

am still a rust noob. so may be wildly wrong
but it seems as if, std::cmd is useful for both:

1. implementing equality and ordering. need the traits there
2. comparing "stuff" implemented with (1). need the Ordering enum here

as a casual user of rust, expected using Ordering to be more important than implementing
traits in std::cmp. in hindsight, this was a bad assumption on my part (maybe)

knee jerk reaction on my part. thinking.

"
i just want to compare two values.
....bit of searching.
Oh. so i need the Ordering enum
"

i guess, it is evident now that:
traits are for implementing stuff
and Enums are for using it

suggestions:

1. docs for std::cmp has examples for both
   • using Ordering
   • implementing a custom ordering
2. a link to Ordering in the text as well

also the example for std::cmp does not tell me anything about using the module