Add division by zero case to the CheckedDiv comment

[tbu-]

No description provided.

[steveklabnik]

Thank you for the patch! I'm guessing this came out of the reddit thread :)

We've been marking failure as its own section, would you mind making to compliant? That'd look like this:

/// Performs division that's checked against failure.
///
/// # Failure
///
/// If dividing by zero is attempted, this will return `None`.
///
/// If the result would overflow or underflow, this will wrap around.

Make sense?

[tbu-]

The function doesn't fail, maybe I wasn't clear enough with the documentation – if that's the case, please tell me.

Otherwise, is returning None considered failure now?

[steveklabnik]

Actually, I guess in this case it's a small semantic difference. I can totally see it both ways. This function can't fail, exactly. Hrm.

[reem]

I was also under the impressions that the # Failure section was for literal calls to fail!() and that when a function returns None that is not failure per se. I think having an explicit marker for actual task failure is very important because it's not annotated in the type that it's even possible - when a function returns None should be a different section.

[steveklabnik]

I'd also consider # Failure to be like things that return Result as well. Option may be too far.

[aturon]

The current convention is to use # Failure for actual calls to fail!. This is a perfect example of why fail is poorly named :-)

A common convention is to use # Errors when producing a Result, see http://static.rust-lang.org/doc/master/std/io/trait.Writer.html#tymethod.write

[lilyball]

# Failure definitely means task failure. So that's explicit calls to fail!(), to assert!(), and to other functions that may fail.

[Gankra]

Should Checked* possibly return a Result then, since it's essentially "bad input" error?

[lilyball]

Theoretically yes, though all our current APIs that behave in this fashion (Checked*, ToPrimitive, etc) all use Option.

Although there is also the argument that this isn't really an error, that it is in fact a valid result that indicates that the operation has no meaning, just like NaN in floating-point calculations. In other words, nothing actually went wrong.

[tbu-]

This is going offtopic. :)

[steveklabnik]

Right, this is a weird case.

I think this patch is good enough for now, as it's clearly an improvement.