From 8fe33a340b8979a73fa84f201c15519a9b5d0266 Mon Sep 17 00:00:00 2001
From: Tavian Barnes <tavianator@gmail.com>
Date: Sun, 14 Nov 2010 21:20:43 -0500
Subject: Document libdimension with Doxygen.

---
 libdimension/dimension/canvas.h | 79 +++++++++++++++++++++++++++++++----------
 1 file changed, 61 insertions(+), 18 deletions(-)

(limited to 'libdimension/dimension/canvas.h')

diff --git a/libdimension/dimension/canvas.h b/libdimension/dimension/canvas.h
index 018dcda..bc98e71 100644
--- a/libdimension/dimension/canvas.h
+++ b/libdimension/dimension/canvas.h
@@ -18,7 +18,8 @@
  * <http://www.gnu.org/licenses/>.                                       *
  *************************************************************************/
 
-/*
+/**
+ * @file
  * A canvas which is rendered to.
  */
 
@@ -27,16 +28,18 @@
 
 #include <stddef.h>
 
+/** A canvas, or image. */
 typedef struct {
-  /* width, height */
-  size_t x, y;
+  size_t width;  /**< Canvas width */
+  size_t height; /**< Canvas height */
 
-  /* An array of dmnsn_canvas_optimizer's */
+  /** An array of <tt>dmnsn_canvas_optimizer</tt>s */
   dmnsn_array *optimizers;
 
-  /*
+  /**
+   * @internal
    * Stored in first-quadrant representation (origin is bottom-left).  The pixel
-   * at (a,b) is accessible as pixels[b*x + a].
+   * at (a,b) is accessible as pixels[b*width + a].
    */
   dmnsn_color *pixels;
 } dmnsn_canvas;
@@ -44,39 +47,79 @@ typedef struct {
 /* Forward-declare dmnsn_canvas_optimizer */
 typedef struct dmnsn_canvas_optimizer dmnsn_canvas_optimizer;
 
-/* Canvas optimizer callback types */
-typedef void dmnsn_canvas_optimizer_fn(dmnsn_canvas *canvas,
+/**
+ * Canvas optimizer callback type.
+ * @param[in] canvas     The canvas that was just updated.
+ * @param[in] optimizer  The canvas optimizer itself.
+ * @param[in] x          The x-coordinate that was just updated.
+ * @param[in] y          The y-coordinate that was just updated.
+ */
+typedef void dmnsn_canvas_optimizer_fn(const dmnsn_canvas *canvas,
                                        dmnsn_canvas_optimizer optimizer,
                                        size_t x, size_t y);
 
-/* Canvas optimizer */
+/** Canvas optimizer */
 struct dmnsn_canvas_optimizer {
-  /* Callback types */
-  dmnsn_canvas_optimizer_fn *optimizer_fn;
-  dmnsn_free_fn             *free_fn;
+  dmnsn_canvas_optimizer_fn *optimizer_fn; /**< Optimizer callback */
+  dmnsn_free_fn             *free_fn;      /**< Destructor callback */
 
-  /* Generic pointer */
-  void *ptr;
+  void *ptr; /**< Generic pointer. */
 };
 
-/* Allocate and free a canvas */
-dmnsn_canvas *dmnsn_new_canvas(size_t x, size_t y);
+/**
+ * Allocate a new canvas.
+ * @param[in] width   The width of the canvas to allocate (in pixels).
+ * @param[in] height  The height of the canvas to allocate (in pixels).
+ * @return The allocated canvas.
+ */
+dmnsn_canvas *dmnsn_new_canvas(size_t width, size_t height);
+
+/**
+ * Delete a canvas.
+ * @param[in,out] canvas  The canvas to delete.
+ */
 void dmnsn_delete_canvas(dmnsn_canvas *canvas);
 
-/* Set a canvas optimizer */
+/**
+ * Set a canvas optimizer
+ * @param[in,out] canvas    The canvas to optimize.
+ * @param[in]     optimizer The optimizer to use.
+ */
 void dmnsn_optimize_canvas(dmnsn_canvas *canvas,
                            dmnsn_canvas_optimizer optimizer);
 
 /* Pixel accessors */
 
+/**
+ * Get the color of a pixel.
+ * @param[in] canvas  The canvas to access.
+ * @param[in] x       The x coordinate.
+ * @param[in] y       The y coordinate.
+ * @return The color of the canvas at (\p x, \p y).
+ */
 DMNSN_INLINE dmnsn_color
 dmnsn_get_pixel(const dmnsn_canvas *canvas, size_t x, size_t y)
 {
-  return canvas->pixels[y*canvas->x + x];
+  dmnsn_assert(x < canvas->width && y < canvas->height,
+               "Canvas access out of bounds.");
+  return canvas->pixels[y*canvas->width + x];
 }
 
+/**
+ * Set the color of a pixel.
+ * @param[in,out] canvas  The canvas to modify.
+ * @param[in]     x       The x coordinate of the pixel.
+ * @param[in]     y       The y coordinate of the pixel.
+ * @param[in]     color   The color to set the pixel at (\p x, \p y) to.
+ */
 void dmnsn_set_pixel(dmnsn_canvas *canvas, size_t x, size_t y,
                      dmnsn_color color);
+
+/**
+ * Clear a canvas uniformly with a given color.
+ * @param[in,out] canvas  The canvas to erase.
+ * @param[in]     color   The color to paint it with.
+ */
 void dmnsn_clear_canvas(dmnsn_canvas *canvas, dmnsn_color color);
 
 #endif /* DIMENSION_CANVAS_H */
-- 
cgit v1.2.3