docs: Add documentation to undocumented public APIs

sorairolake · sorairolake · commit cf1c8ca79614 · 2025-05-10T07:42:57.000+09:00
diff --git a/src/color.rs b/src/color.rs
@@ -41,10 +41,16 @@ impl Color {
         Self { r, g, b, a }
     }
 
+    /// Returns: `[r, g, b, a]`
+    ///
+    /// * Red, green, blue and alpha in the range [0..1]
     pub fn to_array(&self) -> [f32; 4] {
         [self.r, self.g, self.b, self.a]
     }
 
+    /// Returns: `[r, g, b, a]`
+    ///
+    /// * Red, green, blue and alpha in the range [0..255]
     pub fn to_rgba8(&self) -> [u8; 4] {
         [
             (self.r * 255.0 + 0.5) as u8,
@@ -54,6 +60,9 @@ impl Color {
         ]
     }
 
+    /// Returns: `[r, g, b, a]`
+    ///
+    /// * Red, green, blue and alpha in the range [0..65535]
     pub fn to_rgba16(&self) -> [u16; 4] {
         [
             (self.r * 65535.0 + 0.5) as u16,
@@ -63,6 +72,7 @@ impl Color {
         ]
     }
 
+    /// Restricts R, G, B, A values to the range [0..1].
     pub fn clamp(&self) -> Self {
         Self {
             r: self.r.clamp(0.0, 1.0),
@@ -298,6 +308,12 @@ impl Color {
         Self::from_linear_rgba(r, g, b, alpha)
     }
 
+    /// Arguments:
+    ///
+    /// * `l`: Perceived lightness
+    /// * `c`: Chroma
+    /// * `h`: Hue angle in radians
+    /// * `alpha`: Alpha [0..1]
     pub fn from_oklcha(l: f32, c: f32, h: f32, alpha: f32) -> Self {
         Self::from_oklaba(l, c * h.cos(), c * h.sin(), alpha)
     }
@@ -316,6 +332,12 @@ impl Color {
 
     #[cfg(feature = "lab")]
     #[deprecated = "Use [from_laba](#method.from_laba) instead."]
+    /// Arguments:
+    ///
+    /// * `l`: Lightness
+    /// * `a`: Distance along the `a` axis
+    /// * `b`: Distance along the `b` axis
+    /// * `alpha`: Alpha [0..1]
     pub fn from_lab(l: f32, a: f32, b: f32, alpha: f32) -> Self {
         Self::from_laba(l, a, b, alpha)
     }
@@ -329,6 +351,7 @@ impl Color {
 
     #[cfg(feature = "lab")]
     #[deprecated = "Use [to_laba](#method.to_laba) instead."]
+    /// Returns: `[l, a, b, alpha]`
     pub fn to_lab(&self) -> [f32; 4] {
         self.to_laba()
     }
@@ -360,6 +383,12 @@ impl Color {
 
     #[cfg(feature = "lab")]
     #[deprecated = "Use [from_lcha](#method.from_lcha) instead."]
+    /// Arguments:
+    ///
+    /// * `l`: Lightness
+    /// * `c`: Chroma
+    /// * `h`: Hue angle in radians
+    /// * `alpha`: Alpha [0..1]
     pub fn from_lch(l: f32, c: f32, h: f32, alpha: f32) -> Self {
         Self::from_lcha(l, c, h, alpha)
     }
@@ -373,6 +402,7 @@ impl Color {
 
     #[cfg(feature = "lab")]
     #[deprecated = "Use [to_lcha](#method.to_lcha) instead."]
+    /// Returns: `[l, c, h, alpha]`
     pub fn to_lch(&self) -> [f32; 4] {
         self.to_lcha()
     }
diff --git a/src/lib.rs b/src/lib.rs
@@ -99,6 +99,8 @@
 //! * `cint`: Enables converting [`cint`](https://crates.io/crates/cint) crate types to and from `Color`.
 //! * `serde`: Enables serializing (into HEX string) and deserializing (from any supported string color format) using [`serde`](https://serde.rs/) framework.
 
+#![warn(missing_docs)]
+
 mod color;
 pub use color::Color;
 
diff --git a/src/named_colors.rs b/src/named_colors.rs
@@ -1,5 +1,4 @@
-// https://www.w3.org/TR/css-color-4/#named-colors
-
+/// Named colors defined in <https://www.w3.org/TR/css-color-4/#named-colors>.
 pub static NAMED_COLORS: phf::Map<&'static str, [u8; 3]> = phf::phf_map! {
     "aliceblue" => [240, 248, 255],
     "antiquewhite" => [250, 235, 215],
diff --git a/src/parser.rs b/src/parser.rs
@@ -6,20 +6,32 @@ use crate::Color;
 #[cfg(feature = "named-colors")]
 use crate::NAMED_COLORS;
 
+/// An error which can be returned when parsing a CSS color string.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum ParseColorError {
+    /// A CSS color string was invalid hex format.
     InvalidHex,
+    /// A CSS color string was invalid rgb format.
     InvalidRgb,
+    /// A CSS color string was invalid hsl format.
     InvalidHsl,
+    /// A CSS color string was invalid hwb format.
     InvalidHwb,
+    /// A CSS color string was invalid hsv format.
     InvalidHsv,
+    /// A CSS color string was invalid lab format.
     #[cfg(feature = "lab")]
     InvalidLab,
+    /// A CSS color string was invalid lch format.
     #[cfg(feature = "lab")]
     InvalidLch,
+    /// A CSS color string was invalid oklab format.
     InvalidOklab,
+    /// A CSS color string was invalid oklch format.
     InvalidOklch,
+    /// A CSS color string was invalid color function.
     InvalidFunction,
+    /// A CSS color string was invalid unknown format.
     InvalidUnknown,
 }
 

Original file line number	Diff line number	Diff line change
`@@ -41,10 +41,16 @@ impl Color {`
`41`	`41`	`Self { r, g, b, a }`
`42`	`42`	`}`
`43`	`43`
	`44`	+ /// Returns: `[r, g, b, a]`
	`45`	`+ ///`
	`46`	`+ /// * Red, green, blue and alpha in the range [0..1]`
`44`	`47`	`pub fn to_array(&self) -> [f32; 4] {`
`45`	`48`	`[self.r, self.g, self.b, self.a]`
`46`	`49`	`}`
`47`	`50`
	`51`	+ /// Returns: `[r, g, b, a]`
	`52`	`+ ///`
	`53`	`+ /// * Red, green, blue and alpha in the range [0..255]`
`48`	`54`	`pub fn to_rgba8(&self) -> [u8; 4] {`
`49`	`55`	`[`
`50`	`56`	`(self.r * 255.0 + 0.5) as u8,`
`@@ -54,6 +60,9 @@ impl Color {`
`54`	`60`	`]`
`55`	`61`	`}`
`56`	`62`
	`63`	+ /// Returns: `[r, g, b, a]`
	`64`	`+ ///`
	`65`	`+ /// * Red, green, blue and alpha in the range [0..65535]`
`57`	`66`	`pub fn to_rgba16(&self) -> [u16; 4] {`
`58`	`67`	`[`
`59`	`68`	`(self.r * 65535.0 + 0.5) as u16,`
`@@ -63,6 +72,7 @@ impl Color {`
`63`	`72`	`]`
`64`	`73`	`}`
`65`	`74`
	`75`	`+ /// Restricts R, G, B, A values to the range [0..1].`
`66`	`76`	`pub fn clamp(&self) -> Self {`
`67`	`77`	`Self {`
`68`	`78`	`r: self.r.clamp(0.0, 1.0),`
`@@ -298,6 +308,12 @@ impl Color {`
`298`	`308`	`Self::from_linear_rgba(r, g, b, alpha)`
`299`	`309`	`}`
`300`	`310`
	`311`	`+ /// Arguments:`
	`312`	`+ ///`
	`313`	+ /// * `l`: Perceived lightness
	`314`	+ /// * `c`: Chroma
	`315`	+ /// * `h`: Hue angle in radians
	`316`	+ /// * `alpha`: Alpha [0..1]
`301`	`317`	`pub fn from_oklcha(l: f32, c: f32, h: f32, alpha: f32) -> Self {`
`302`	`318`	`Self::from_oklaba(l, c * h.cos(), c * h.sin(), alpha)`
`303`	`319`	`}`
`@@ -316,6 +332,12 @@ impl Color {`
`316`	`332`
`317`	`333`	`#[cfg(feature = "lab")]`
`318`	`334`	`#[deprecated = "Use [from_laba](#method.from_laba) instead."]`
	`335`	`+ /// Arguments:`
	`336`	`+ ///`
	`337`	+ /// * `l`: Lightness
	`338`	+ /// * `a`: Distance along the `a` axis
	`339`	+ /// * `b`: Distance along the `b` axis
	`340`	+ /// * `alpha`: Alpha [0..1]
`319`	`341`	`pub fn from_lab(l: f32, a: f32, b: f32, alpha: f32) -> Self {`
`320`	`342`	`Self::from_laba(l, a, b, alpha)`
`321`	`343`	`}`
`@@ -329,6 +351,7 @@ impl Color {`
`329`	`351`
`330`	`352`	`#[cfg(feature = "lab")]`
`331`	`353`	`#[deprecated = "Use [to_laba](#method.to_laba) instead."]`
	`354`	+ /// Returns: `[l, a, b, alpha]`
`332`	`355`	`pub fn to_lab(&self) -> [f32; 4] {`
`333`	`356`	`self.to_laba()`
`334`	`357`	`}`
`@@ -360,6 +383,12 @@ impl Color {`
`360`	`383`
`361`	`384`	`#[cfg(feature = "lab")]`
`362`	`385`	`#[deprecated = "Use [from_lcha](#method.from_lcha) instead."]`
	`386`	`+ /// Arguments:`
	`387`	`+ ///`
	`388`	+ /// * `l`: Lightness
	`389`	+ /// * `c`: Chroma
	`390`	+ /// * `h`: Hue angle in radians
	`391`	+ /// * `alpha`: Alpha [0..1]
`363`	`392`	`pub fn from_lch(l: f32, c: f32, h: f32, alpha: f32) -> Self {`
`364`	`393`	`Self::from_lcha(l, c, h, alpha)`
`365`	`394`	`}`
`@@ -373,6 +402,7 @@ impl Color {`
`373`	`402`
`374`	`403`	`#[cfg(feature = "lab")]`
`375`	`404`	`#[deprecated = "Use [to_lcha](#method.to_lcha) instead."]`
	`405`	+ /// Returns: `[l, c, h, alpha]`
`376`	`406`	`pub fn to_lch(&self) -> [f32; 4] {`
`377`	`407`	`self.to_lcha()`
`378`	`408`	`}`