From e479a77b623f4eb7d9b30e6c7d1fc1eff809e0cf Mon Sep 17 00:00:00 2001
From: David Peter <mail@david-peter.de>
Date: Thu, 29 Aug 2024 21:23:18 +0200
Subject: [PATCH] Add documentation

---
 book/src/list-functions-other.md | 5 +++++
 examples/tests/color.nbt         | 2 ++
 numbat/modules/all.nbt           | 1 +
 numbat/modules/extra/color.nbt   | 5 +++++
 numbat/modules/prelude.nbt       | 2 --
 5 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/book/src/list-functions-other.md b/book/src/list-functions-other.md
index e7ad95e9..a8a97830 100644
--- a/book/src/list-functions-other.md
+++ b/book/src/list-functions-other.md
@@ -146,30 +146,35 @@ fn fahrenheit(t_kelvin: Temperature) -> Scalar
 Defined in: `extra::color`
 
 ### `rgb`
+Create a `Color` from RGB (red, green, blue) values in the range \\( [0, 256) \\).
 
 ```nbt
 fn rgb(red: Scalar, green: Scalar, blue: Scalar) -> Color
 ```
 
 ### `color`
+Create a `Color` from a (hexadecimal) value, e.g. `color(0xff7700)`.
 
 ```nbt
 fn color(rgb_hex: Scalar) -> Color
 ```
 
 ### `color_rgb`
+Convert a color to its RGB representation, e.g. `cyan -> color_rgb`.
 
 ```nbt
 fn color_rgb(color: Color) -> String
 ```
 
 ### `color_rgb_float`
+Convert a color to its RGB floating point representation, e.g. `cyan -> color_rgb_float`.
 
 ```nbt
 fn color_rgb_float(color: Color) -> String
 ```
 
 ### `color_hex`
+Convert a color to its hexadecimal representation, e.g. `rgb(225, 36, 143) -> color_hex`.
 
 ```nbt
 fn color_hex(color: Color) -> String
diff --git a/examples/tests/color.nbt b/examples/tests/color.nbt
index bbe6ae4a..78536607 100644
--- a/examples/tests/color.nbt
+++ b/examples/tests/color.nbt
@@ -1,3 +1,5 @@
+use extra::color
+
 assert_eq(0x000000 -> color, black)
 assert_eq(0xffffff -> color, white)
 assert_eq(0x123456 -> color, Color { red: 0x12, green: 0x34, blue: 0x56 })
diff --git a/numbat/modules/all.nbt b/numbat/modules/all.nbt
index 063dfd93..84b7a1d8 100644
--- a/numbat/modules/all.nbt
+++ b/numbat/modules/all.nbt
@@ -5,6 +5,7 @@ use units::stoney
 use units::hartree
 
 use extra::algebra
+use extra::color
 
 use numerics::diff
 use numerics::solve
diff --git a/numbat/modules/extra/color.nbt b/numbat/modules/extra/color.nbt
index 6c257ee8..6b50c20a 100644
--- a/numbat/modules/extra/color.nbt
+++ b/numbat/modules/extra/color.nbt
@@ -8,9 +8,11 @@ struct Color {
   blue: Scalar,
 }
 
+@description("Create a `Color` from RGB (red, green, blue) values in the range $[0, 256)$.")
 fn rgb(red: Scalar, green: Scalar, blue: Scalar) -> Color =
   Color { red: red, green: green, blue: blue }
 
+@description("Create a `Color` from a (hexadecimal) value, e.g. `color(0xff7700)`")
 fn color(rgb_hex: Scalar) -> Color =
   rgb(
     floor(rgb_hex / 256^2),
@@ -20,12 +22,15 @@ fn color(rgb_hex: Scalar) -> Color =
 fn _color_to_scalar(color: Color) -> Scalar =
   color.red * 0x010000 + color.green * 0x000100 + color.blue
 
+@description("Convert a color to its RGB representation, e.g. `cyan -> color_rgb`")
 fn color_rgb(color: Color) -> String =
   "rgb({color.red}, {color.green}, {color.blue})"
 
+@description("Convert a color to its RGB floating point representation, e.g. `cyan -> color_rgb_float`")
 fn color_rgb_float(color: Color) -> String =
   "rgb({color.red / 255:.3}, {color.green / 255:.3}, {color.blue / 255:.3})"
 
+@description("Convert a color to its hexadecimal representation, e.g. `rgb(225, 36, 143) -> color_hex`")
 fn color_hex(color: Color) -> String =
   str_append("#", str_replace(str_replace("{color -> _color_to_scalar -> hex:>8}", "0x", ""), " ", "0"))
 
diff --git a/numbat/modules/prelude.nbt b/numbat/modules/prelude.nbt
index 37e6b40c..1b15a549 100644
--- a/numbat/modules/prelude.nbt
+++ b/numbat/modules/prelude.nbt
@@ -42,5 +42,3 @@ use chemistry::elements
 
 use datetime::functions
 use datetime::human
-
-use extra::color