From b9e19e076662ae5743b9c81eb238fe11204f6dbd Mon Sep 17 00:00:00 2001
From: Tavian Barnes <tavianator@gmail.com>
Date: Sun, 12 Apr 2009 19:06:50 +0000
Subject: Add some comments.

---
 libdimension/dimension/canvas.h   |  8 ++++----
 libdimension/dimension/color.h    | 13 +++++--------
 libdimension/dimension/error.h    | 10 +++++++---
 libdimension/dimension/geometry.h |  5 +++--
 4 files changed, 19 insertions(+), 17 deletions(-)

(limited to 'libdimension/dimension')

diff --git a/libdimension/dimension/canvas.h b/libdimension/dimension/canvas.h
index 4449403..f05264b 100644
--- a/libdimension/dimension/canvas.h
+++ b/libdimension/dimension/canvas.h
@@ -18,15 +18,14 @@
  * <http://www.gnu.org/licenses/>.                                       *
  *************************************************************************/
 
-/*
- * A canvas which is rendered to.
- */
-
 #ifndef DIMENSION_CANVAS_H
 #define DIMENSION_CANVAS_H
 
 #include <pthread.h>
 
+/*
+ * A canvas which is rendered to.
+ */
 typedef struct {
   unsigned int x, y;
 
@@ -40,6 +39,7 @@ typedef struct {
   pthread_rwlock_t *rwlocks;
 } dmnsn_canvas;
 
+/* Allocate and free a canvas */
 dmnsn_canvas *dmnsn_new_canvas(unsigned int x, unsigned int y);
 void dmnsn_delete_canvas(dmnsn_canvas *canvas);
 
diff --git a/libdimension/dimension/color.h b/libdimension/dimension/color.h
index 0e64875..f1964c3 100644
--- a/libdimension/dimension/color.h
+++ b/libdimension/dimension/color.h
@@ -25,10 +25,6 @@
 #ifndef DIMENSION_COLOR_H
 #define DIMENSION_COLOR_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif
-
 /* Internally, we use CIE 1931 XYZ color. */
 typedef struct {
   double X, Y, Z;
@@ -67,6 +63,8 @@ typedef struct {
 /* Standard whitepoint, determined by the conversion of sRGB white to XYZ */
 extern const dmnsn_CIE_XYZ dmnsn_whitepoint;
 
+/* Color conversions */
+
 dmnsn_color dmnsn_color_from_XYZ(dmnsn_CIE_XYZ XYZ);
 dmnsn_color dmnsn_color_from_xyY(dmnsn_CIE_xyY xyY);
 dmnsn_color dmnsn_color_from_Lab(dmnsn_CIE_Lab Lab, dmnsn_CIE_XYZ white);
@@ -79,11 +77,10 @@ dmnsn_CIE_Lab dmnsn_Lab_from_color(dmnsn_color color, dmnsn_CIE_XYZ white);
 dmnsn_CIE_Luv dmnsn_Luv_from_color(dmnsn_color color, dmnsn_CIE_XYZ white);
 dmnsn_sRGB    dmnsn_sRGB_from_color(dmnsn_color color);
 
+/* Perceptually correct color combination */
 dmnsn_color dmnsn_color_add(dmnsn_color color1, dmnsn_color color2);
-double dmnsn_color_difference(dmnsn_color color1, dmnsn_color color2);
 
-#ifdef __cplusplus
-}
-#endif
+/* Perceptual color difference */
+double dmnsn_color_difference(dmnsn_color color1, dmnsn_color color2);
 
 #endif /* DIMENSION_COLOR_H */
diff --git a/libdimension/dimension/error.h b/libdimension/dimension/error.h
index 2c00a4a..858ff96 100644
--- a/libdimension/dimension/error.h
+++ b/libdimension/dimension/error.h
@@ -18,24 +18,28 @@
  * <http://www.gnu.org/licenses/>.                                       *
  *************************************************************************/
 
+#ifndef DIMENSION_ERROR_H
+#define DIMENSION_ERROR_H
+
 /*
  * Error handling.
  */
 
-#ifndef DIMENSION_ERROR_H
-#define DIMENSION_ERROR_H
-
 typedef enum {
   DMNSN_SEVERITY_LOW,    /* Only die on low resilience */
   DMNSN_SEVERITY_MEDIUM, /* Die on low or medium resilience */
   DMNSN_SEVERITY_HIGH    /* Always die */
 } dmnsn_severity;
 
+/* Use this to report an error */
 #define dmnsn_error(severity, str)                              \
   dmnsn_report_error(severity, __PRETTY_FUNCTION__, __LINE__, str)
 
+/* Called by dmnsn_error() - don't call directly */
 void dmnsn_report_error(dmnsn_severity severity,
                         const char *func, unsigned int line, const char *str);
+
+/* Get and set the library resilience, thread-safely */
 dmnsn_severity dmnsn_get_resilience();
 void dmnsn_set_resilience(dmnsn_severity resilience);
 
diff --git a/libdimension/dimension/geometry.h b/libdimension/dimension/geometry.h
index 26705ca..e1d1497 100644
--- a/libdimension/dimension/geometry.h
+++ b/libdimension/dimension/geometry.h
@@ -29,12 +29,13 @@
 typedef double                           dmnsn_scalar;
 typedef struct { dmnsn_scalar x, y, z; } dmnsn_vector;
 
-/* Vector arithmetic */
-
+/* Shorthand for vector construction */
 dmnsn_vector dmnsn_vector_construct(dmnsn_scalar x,
                                     dmnsn_scalar y,
                                     dmnsn_scalar z);
 
+/* Vector arithmetic */
+
 dmnsn_vector dmnsn_vector_add(dmnsn_vector lhs, dmnsn_vector rhs);
 dmnsn_vector dmnsn_vector_sub(dmnsn_vector lhs, dmnsn_vector rhs);
 dmnsn_vector dmnsn_vector_mul(dmnsn_scalar lhs, dmnsn_vector rhs);
-- 
cgit v1.2.3