Documentation for abs() on signed integers doesn't mention unsigned_abs()

[Architector4]

Location

https://doc.rust-lang.org/std/primitive.i8.html#method.abs
https://doc.rust-lang.org/std/primitive.i16.html#method.abs
https://doc.rust-lang.org/std/primitive.i32.html#method.abs
https://doc.rust-lang.org/std/primitive.i64.html#method.abs
https://doc.rust-lang.org/std/primitive.i128.html#method.abs

Summary

The documentation mentions that the abs method could cause undesired behavior in case a MIN value of the type is passed.

It could use a mention of the unsigned_abs method after this, which can fit all possible return values at cost of converting the value to an unsigned integer instead, which may have been the behavior one wanted when looking for this function in the documentation.

It doesn't help that alphabetically unsigned_abs is sorted all the way down, while abs sits all the way up. A programmer could end up seeing only abs, and assume that they need to either specially handle MIN value, or use the immediately visible abs_diff function below that, with second parameter set to 0 to achieve the wanted effect. (the latter could use a clippy lint? lol)

[gurry]

@rustbot claim