Add documentation

sharkdp · Aug 29, 2024 · e479a77 · e479a77
1 parent 34b470f
commit e479a77
Show file tree

Hide file tree

Showing 5 changed files with 13 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -42,5 +42,3 @@ use chemistry::elements
 
 use datetime::functions
 use datetime::human
-
-use extra::color