Document division by zero

2 files changed, 26 insertions, 0 deletions

diff --git a/src/gleam/float.gleam b/src/gleam/float.gleam
index 59789fc..5d62419 100644
--- a/src/gleam/float.gleam
+++ b/src/gleam/float.gleam
@@ -1,3 +1,17 @@
+//// Functions for working with floats.
+////
+//// ## Division by zero
+////
+//// Gleam runs on the Erlang virtual machine, which does not follow the IEEE
+//// 754 standard for floating point arithmetic and does not have an `Infinity`
+//// value.  In Erlang division by zero results in a crash, however Gleam does
+//// not have partial functions and operators in core so instead division by zero
+//// returns zero, a behaviour taken from Pony, Coq, and Lean.
+////
+//// This may seem unexpected at first, but it is no less mathematically valid
+//// than crashing or returning a special value. Division by zero is undefined
+//// in mathematics.
+
 import gleam/order.{type Order}
 
 /// Attempts to parse a string as a `Float`, returning `Error(Nil)` if it was
diff --git a/src/gleam/int.gleam b/src/gleam/int.gleam
index 8b3b89e..d93c16a 100644
--- a/src/gleam/int.gleam
+++ b/src/gleam/int.gleam
@@ -1,3 +1,15 @@
+//// Functions for working with integers.
+////
+//// ## Division by zero
+////
+//// In Erlang division by zero results in a crash, however Gleam does not have
+//// partial functions and operators in core so instead division by zero returns
+//// zero, a behaviour taken from Pony, Coq, and Lean.
+////
+//// This may seem unexpected at first, but it is no less mathematically valid
+//// than crashing or returning a special value. Division by zero is undefined
+//// in mathematics.
+
 import gleam/float
 import gleam/order.{type Order}