Make int.modulo and float.modulo docs clearer

src/gleam/float.gleam

@@ -456,6 +456,8 @@ pub fn random() -> Float
 /// Returns division of the inputs as a `Result`: If the given divisor equals
 /// `0`, this function returns an `Error`.
 ///
+/// The computed value will always have the same sign as the `divisor`.
+///
 /// ## Examples
 ///
 /// ```gleam

src/gleam/int.gleam

@@ -594,8 +594,8 @@ pub fn remainder(dividend: Int, by divisor: Int) -> Result(Int, Nil) {
 /// Returns division of the inputs as a `Result`: If the given divisor equals
 /// `0`, this function returns an `Error`.
 ///
-/// Most the time you will want to use the `%` operator instead of this
-/// function.
+/// Note that this is different from `int.remainder` and `%` in that the
+/// computed value will always have the same sign as the `divisor`.
 ///
 /// ## Examples
 ///
@@ -624,6 +624,11 @@ pub fn remainder(dividend: Int, by divisor: Int) -> Result(Int, Nil) {
 /// // -> Ok(2)
 /// ```
 ///
+/// ```gleam
+/// modulo(13, by: -3)
+/// // -> Ok(-2)
+/// ```
+///
 pub fn modulo(dividend: Int, by divisor: Int) -> Result(Int, Nil) {
   case divisor {
     0 -> Error(Nil)