diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 83bfa6e6..106cb6db 100644
--- a/src/gleam/float.gleam
+++ b/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
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index fa8aaef8..c0cd069e 100644
--- a/src/gleam/int.gleam
+++ b/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)