[std::cmp] add missing docs and provide an example

[killerswan]

No description provided.

[huonw]

I would prefer this to be a normal struct like struct SketchyNum { num: int } so that the implementation below can be

(self.num - other.num).abs() < 5

for clarity. (It does makes the assertions slightly uglier, but not extremely so.)

[killerswan]

Yeah, not bad at all.

[alexcrichton]

This looks great! Could you squash the commits into one?

Also, feel free to comment on the PR whenever you force-push, sadly github doesn't send out updates when that happens!

[killerswan]

Squished!

[killerswan]

Am I supposed to do something here?

[alexcrichton]

The test run failed on bors. It looks like some of the new documentation examples failed when tested.

You can run the tests yourself via make check-stage1-doc-crate-std and then after that you can pass NO_REBUILD=1 to avoid the full bootstrap.

[killerswan]

How do I see which tests failed on bors? None of the logs I see has anything to do with what I changed here...

[alexcrichton]

Bors left a comment on the commit (#12956 (comment)) and it's the link marked failure:

[killerswan]

FWIW, I've rebased to the latest master. There, somebody'd added a special case for cfg0 and so it was missing a doc comment, and I've added one for it.

Still compiling, though.

[killerswan]

Well, so much for that:

$ make check-stage1-doc-crate-std
...
oxidize: x86_64-apple-darwin/stage0/lib/rustlib/x86_64-apple-darwin/bin/compiletest
/Users/kevin/code/rust/src/compiletest/compiletest.rs:1:1: 1:1 error: can't find crate for `native`
/Users/kevin/code/rust/src/compiletest/compiletest.rs:1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
                                                        ^
error: aborting due to previous error
make: *** [x86_64-apple-darwin/stage0/lib/rustlib/x86_64-apple-darwin/bin/compiletest] Error 101

[alexcrichton]

Ah sorry about that, looks like the dependencies are a bit off for the makefiles. Regardless, the travis build passed, which is now running tests, so I think this is good to go.

[killerswan]

/me crosses fingers

[killerswan]

This latest failure boils down to this, for example:

    <anon>:8:13: 8:23 error: multiple applicable methods in scope
    <anon>:8 assert_eq!( 5.cmp(&10), Less);     // because 5 < 10
                         ^~~~~~~~~~
    <std macros>:1:1: 12:2 note: in expansion of assert_eq!
    <anon>:8:1: 8:31 note: expansion site
    <anon>:8:13: 8:23 note: candidate #1 is `std::cmp::u8.TotalOrd::cmp`
    <anon>:8 assert_eq!( 5.cmp(&10), Less);     // because 5 < 10
                         ^~~~~~~~~~
    <std macros>:1:1: 12:2 note: in expansion of assert_eq!
    <anon>:8:1: 8:31 note: expansion site
    <anon>:8:13: 8:23 note: candidate #2 is `std::cmp::u16.TotalOrd::cmp`
    <anon>:8 assert_eq!( 5.cmp(&10), Less);     // because 5 < 10
                         ^~~~~~~~~~

Is there an easy way to tell rustc what kind of integer literal each of these should be by default?

[huonw]

Just add a suffix, e.g. 5u.cmp(&10) to force the 5 to be a uint (and then inference works for the 10).

[killerswan]

What have I changed, though, which caused this to break?

[killerswan]

Also still having trouble compiling locally:

/Users/kevin/code/rust/src/compiletest/compiletest.rs:1:1: 1:1 error: found possibly newer version of crate `std` which `native` depends on
/Users/kevin/code/rust/src/compiletest/compiletest.rs:1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
                                                        ^
/Users/kevin/code/rust/src/compiletest/compiletest.rs:1:1: 1:1 note: perhaps this crate needs to be recompiled?
/Users/kevin/code/rust/src/compiletest/compiletest.rs:1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
                                                        ^
error: aborting due to previous error
make: *** [x86_64-apple-darwin/stage0/lib/rustlib/x86_64-apple-darwin/bin/compiletest] Error 101

So I'm about to send in another change and we'll see...

[killerswan]

From the looks of that error message I didn't push my last commit. I'll check in tomorrow.

[killerswan]

Just rebased again (now: 971c90248e978bf7). Still seeing that "native" error and haven't necessarily sorted everything out, yet, sadly...

[alexcrichton]

I would recommend running make check before we r+ it again to make sure that it's passing. Alternatively, you can build rustdoc and then run rustdoc --test src/libstd/lib.rs

[thestinger]

This block comment doesn't really make sense.

[killerswan]

Ah, true, but I'd been confused why the other had been inserted and then swapped with this. (Now I get it: we were waiting on another snapshot.)

[killerswan]

Rebased and pushed 99fa22515, which went through make check OK, but obviously has failed elsewhere for Travis CI: possibly something to do with LLVM 3.4? But I'm going to try again for good measure with 02c9c94.

[killerswan]

/me crosses fingers

[killerswan]

Yay! Thanks @alexcrichton and @huonw and @thestinger. And @bors.