Document libdimension with Doxygen.

1 files changed, 110 insertions, 30 deletions

diff --git a/libdimension/dimension/texture.h b/libdimension/dimension/texture.h
index 5586e24..f582351 100644
--- a/libdimension/dimension/texture.h
+++ b/libdimension/dimension/texture.h
@@ -18,7 +18,8 @@
  * <http://www.gnu.org/licenses/>.                                       *
  *************************************************************************/
 
-/*
+/**
+ * @file
  * Object textures.
  */
 
@@ -32,31 +33,55 @@
 /* Forward-declare dmnsn_pigment */
 typedef struct dmnsn_pigment dmnsn_pigment;
 
-/* Pigment callbacks */
+/**
+ * Pigment callback.
+ * @param[in] pigment  The pigment itself.
+ * @param[in] v        The point to color.
+ * @return The color of the pigment at \p v.
+ */
 typedef dmnsn_color dmnsn_pigment_fn(const dmnsn_pigment *pigment,
                                      dmnsn_vector v);
+
+/**
+ * Pigment initializer callback.
+ * @param[in,out] pigment  The pigment to initialize.
+ */
 typedef void dmnsn_pigment_init_fn(dmnsn_pigment *pigment);
 
-/* dmnsn_pigment definition */
+/** A pigment */
 struct dmnsn_pigment {
-  /* Callbacks */
-  dmnsn_pigment_fn *pigment_fn;
-  dmnsn_pigment_init_fn *init_fn;
-  dmnsn_free_fn *free_fn;
+  dmnsn_pigment_fn *pigment_fn;   /**< The pigment callback. */
+  dmnsn_pigment_init_fn *init_fn; /**< The initializer callback. */
+  dmnsn_free_fn *free_fn;         /**< The destructor callback. */
 
-  /* Transformation matrix */
-  dmnsn_matrix trans, trans_inv;
+  dmnsn_matrix trans;     /**< Transformation matrix. */
+  dmnsn_matrix trans_inv; /**< The inverse of the transformation matrix. */
 
-  /* Quick color */
+  /** Quick color -- used for low-quality renders. */
   dmnsn_color quick_color;
 
-  /* Generic pointer */
+  /** Generic pointer */
   void *ptr;
 };
 
+/**
+ * Allocate a new dummy pigment.
+ * @return The allocated pigment.
+ */
 dmnsn_pigment *dmnsn_new_pigment(void);
+
+/**
+ * Delete a pigment.
+ * @param[in,out] pigment  The pigment to delete.
+ */
 void dmnsn_delete_pigment(dmnsn_pigment *pigment);
 
+/**
+ * Initialize a pigment.  Pigments should not be used before being initialized,
+ * but should not be modified after being initialized.  Pigments are generally
+ * initialized for you.
+ * @param[in,out] pigment  The pigment to initialize.
+ */
 void dmnsn_pigment_init(dmnsn_pigment *pigment);
 
 /*
@@ -66,56 +91,111 @@ void dmnsn_pigment_init(dmnsn_pigment *pigment);
 /* Forward-declare dmnsn_finish */
 typedef struct dmnsn_finish dmnsn_finish;
 
-/* Finish callbacks */
+/**
+ * Diffuse reflection callback.
+ * @param[in] finish  The finish itself.
+ * @param[in] light   The color of the light illuminating the object.
+ * @param[in] color   The pigment of the object.
+ * @param[in] ray     The direction of the light source.
+ * @param[in] normal  The normal vector of the surface.
+ * @return The diffuse reflection component of the object's color.
+ */
 typedef dmnsn_color dmnsn_diffuse_fn(const dmnsn_finish *finish,
                                      dmnsn_color light, dmnsn_color color,
                                      dmnsn_vector ray, dmnsn_vector normal);
+/**
+ * Specular highlight callback.
+ * @param[in] finish  The finish itself.
+ * @param[in] light   The color of the light illuminating the object.
+ * @param[in] color   The pigment of the object.
+ * @param[in] ray     The direction of the light source.
+ * @param[in] normal  The normal vector of the surface.
+ * @param[in] viewer  The direction of the viewer.
+ * @return The specular reflection component of the object's color.
+ */
 typedef dmnsn_color dmnsn_specular_fn(const dmnsn_finish *finish,
                                       dmnsn_color light, dmnsn_color color,
                                       dmnsn_vector ray, dmnsn_vector normal,
                                       dmnsn_vector viewer);
+/**
+ * Ambient light callback.
+ * @param[in] finish   The finish itself.
+ * @param[in] pigment  The pigment of the object.
+ * @return The ambient contribution to the object's color.
+ */
 typedef dmnsn_color dmnsn_ambient_fn(const dmnsn_finish *finish,
                                      dmnsn_color pigment);
+/**
+ * Reflected light callback.
+ * @param[in] finish   The finish itself.
+ * @param[in] reflect  The color of the reflected ray.
+ * @param[in] color    The pigment of the object.
+ * @param[in] ray      The direction of the reflected ray.
+ * @param[in] normal   The normal vector of the surface.
+ * @return The contribution of the reflected ray to the object's color.
+ */
 typedef dmnsn_color dmnsn_reflection_fn(const dmnsn_finish *finish,
                                         dmnsn_color reflect, dmnsn_color color,
                                         dmnsn_vector ray, dmnsn_vector normal);
 
-/* dmnsn_finish definition */
+/** A finish. */
 struct dmnsn_finish {
-  /* Callbacks */
-  dmnsn_diffuse_fn    *diffuse_fn;
-  dmnsn_specular_fn   *specular_fn;
-  dmnsn_ambient_fn    *ambient_fn;
-  dmnsn_reflection_fn *reflection_fn;
-  dmnsn_free_fn       *free_fn;
-
-  /* Generic pointer */
+  dmnsn_diffuse_fn    *diffuse_fn;    /**< The diffuse callback. */
+  dmnsn_specular_fn   *specular_fn;   /**< The specular callback. */
+  dmnsn_ambient_fn    *ambient_fn;    /**< The ambient callback. */
+  dmnsn_reflection_fn *reflection_fn; /**< The reflection callback. */
+  dmnsn_free_fn       *free_fn;       /**< The destruction callback. */
+
+  /** Generic pointer */
   void *ptr;
 };
 
+/**
+ * Allocate a new dummy finish.
+ * @return The allocated finish.
+ */
 dmnsn_finish *dmnsn_new_finish(void);
+
+/**
+ * Delete a finish.
+ * @param[in,out] finish  The finish to delete.
+ */
 void dmnsn_delete_finish(dmnsn_finish *finish);
 
 /*
- * A complete texture
+ * Textures
  */
 
+/** A complete texture. */
 typedef struct {
-  /* Texture components */
-  dmnsn_pigment *pigment;
-  dmnsn_finish  *finish;
+  dmnsn_pigment *pigment; /**< Pigment. */
+  dmnsn_finish  *finish;  /**< Finish. */
 
-  /* Transformation matrix */
-  dmnsn_matrix trans, trans_inv;
+  dmnsn_matrix trans;     /**< Transformation matrix. */
+  dmnsn_matrix trans_inv; /**< The inverse of the transformation matrix. */
 
-  /* Reference count */
-  unsigned int *refcount;
-  bool should_init;
+  unsigned int *refcount; /**< @internal Reference count. */
+  bool should_init;       /**< @internal Whether to init the texture. */
 } dmnsn_texture;
 
+/**
+ * Create a blank texture.
+ * @return The new texture.
+ */
 dmnsn_texture *dmnsn_new_texture(void);
+
+/**
+ * Delete a texture.
+ * @param[in,out] texture  The texture to delete.
+ */
 void dmnsn_delete_texture(dmnsn_texture *texture);
 
+/**
+ * Initialize a texture.  Textures should not be used before being initialized,
+ * but should not be modified after being initialized.  Textures are generally
+ * initialized for you.
+ * @param[in,out] texture  The texture to initialize.
+ */
 void dmnsn_texture_init(dmnsn_texture *texture);
 
 #endif /* DIMENSION_TEXTURE_H */