Improve Documentation

[JP-Ellis]

The documentation currently is not very clear as to how it computes things, and one reason I think is that nearly all the example just compare whether 1.0 is approximately equal to 1.0 which isn't very illustrative.

It would be good if there were examples at the crate level showing the differences between the various macros that illustrate when one should use abs_diff_eq! vs relative_eq! vs ulps_eq!. Additionally, the documentation for each macro is quite lacking (e.g. assert_relative_eq and relative_eq are not very helpful).

It is also unclear from the documentation what keyword arguments are allowed in which macros. Are the crate-level examples exhaustive ? Or can I also use max_relative in the ulps_eq! macro? Does the order matter? Because the examples show both:

relative_eq!(1.0, 1.0, epsilon = f64::EPSILON, max_relative = 1.0);
relative_eq!(1.0, 1.0, max_relative = 1.0, epsilon = f64::EPSILON);

What if I want to assert that two results should have "x decimal digits in common", is this possible?

[JP-Ellis]

I have come back around to this crate seeing as it had a few updates hoping that the documentation has improved a little bit, and unfortunately it doesn't seem like it. If someone created a pull request, would there be interest in this?

[vilcans]

I agree. I had to dig through the code to try to figure out what the arguments to the macros mean. It would be much appreciated if the documentation briefly explained what epsilon, max_relative, and max_ulps are and how they're supposed to be used. Examples and tables of successful and unsuccessful comparison would help.

These are my notes with simplified formulas without special cases, maybe this can be a start. Disclaimer: I may be wrong! I'm sure @sebcrozet can clarify.

Absolute difference: Absolute difference between values, not heeding their magnitude: abs(a - b) <= epsilon. Simple and intuitive, but often the wrong way to check for equality. Default epsilon is f32::EPSILON or f64::EPSILON, which only give the correct result if the numbers are between 1.0 and 2.0. Use case: Checking that a value is within a reasonable range?

Relative difference: Scales the max allowed difference with the magnitude of the numbers: abs(a - b) / max(abs(a), abs(b)) <= max_relative. What's a good value for max_relative? The default is the same as epsilon.

ULPS (Units in Last Place): Compares the difference after interpreting the bit pattern of the floating point values as integers. Described well (although long) at https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/. Still unclear to me how to choose max_ulps. The default is 4. Trial and error?