From 9288d6fe4d444094e7f6909ee5621d8cfc4103d5 Mon Sep 17 00:00:00 2001
From: Andrew Belt <andrewpbelt@gmail.com>
Date: Thu, 27 Jun 2024 10:32:02 -0400
Subject: [PATCH] Improve color:: doc comments.

---
 include/color.hpp | 34 ++++++++++++++++++++++++++--------
 src/color.cpp     |  1 -
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/include/color.hpp b/include/color.hpp
index a32868f4..e74a8b0d 100644
--- a/include/color.hpp
+++ b/include/color.hpp
@@ -24,26 +24,44 @@ static const NVGcolor YELLOW = nvgRGB(0xff, 0xff, 0x00);
 static const NVGcolor WHITE = nvgRGB(0xff, 0xff, 0xff);
 
 
+/** Returns whether all RGBA color components are equal. */
 bool isEqual(NVGcolor a, NVGcolor b);
-/** Limits color components between 0 and 1. */
+/** Limits RGBA color components between 0 and 1. */
 NVGcolor clamp(NVGcolor a);
-/** Subtracts color components elementwise. */
+/** Subtracts RGB color components elementwise.
+Alpha value is copied from `a`.
+*/
 NVGcolor minus(NVGcolor a, NVGcolor b);
-/** Adds color components elementwise. */
+/** Adds RGB color components elementwise.
+Alpha value is copied from `a`.
+*/
 NVGcolor plus(NVGcolor a, NVGcolor b);
-/** Multiplies color components elementwise. */
+/** Multiplies RGB color components elementwise.
+Alpha value is copied from `a`.
+*/
 NVGcolor mult(NVGcolor a, NVGcolor b);
+/** Multiplies RGB color components by a scalar.
+Alpha value is untouched.
+*/
 NVGcolor mult(NVGcolor a, float x);
-/** Interpolates RGBA color values. */
+/** Interpolates RGBA color components. */
 NVGcolor lerp(NVGcolor a, NVGcolor b, float t);
-/** Screen blending with alpha compositing */
+/** Screen blending with alpha compositing.
+https://en.wikipedia.org/wiki/Blend_modes#Screen
+*/
 NVGcolor screen(NVGcolor a, NVGcolor b);
-/** Multiplies alpha value. */
+/** Multiplies alpha value by a scalar.
+RGB color components are untouched.
+*/
 NVGcolor alpha(NVGcolor a, float alpha);
-/** Converts from color hex string of the form "#RRGGBB" or "#RRGGBBAA".
+/** Converts from hex string of the form "#RRGGBB" or "#RRGGBBAA".
+Must include "#".
 Returns WHITE on error.
 */
 NVGcolor fromHexString(std::string s);
+/** Converts color to hex string of the form "#RRGGBB" if opaque or "#RRGGBBAA" if alpha < 255.
+Floating point color components are rounded to nearest 8-bit integer.
+*/
 std::string toHexString(NVGcolor c);
 
 
diff --git a/src/color.cpp b/src/color.cpp
index 3c90a756..eb11e1fa 100644
--- a/src/color.cpp
+++ b/src/color.cpp
@@ -51,7 +51,6 @@ NVGcolor lerp(NVGcolor a, NVGcolor b, float t) {
 	return c;
 }
 
-/** Screen blending with alpha compositing */
 NVGcolor screen(NVGcolor a, NVGcolor b) {
 	if (a.a == 0.f)
 		return b;