Document libdimension with Doxygen.

1 files changed, 38 insertions, 12 deletions

diff --git a/libdimension/dimension/pattern.h b/libdimension/dimension/pattern.h
index 6301372..9636155 100644
--- a/libdimension/dimension/pattern.h
+++ b/libdimension/dimension/pattern.h
@@ -18,8 +18,10 @@
  * <http://www.gnu.org/licenses/>.                                       *
  *************************************************************************/
 
-/*
- * Patterns
+/**
+ * @file
+ * Patterns.  Patterns are functions which map vectors to scalars, which are
+ * used for pigments and normals.
  */
 
 #ifndef DIMENSION_PATTERN_H
@@ -28,28 +30,52 @@
 /* Forward-declare dmnsn_pattern */
 typedef struct dmnsn_pattern dmnsn_pattern;
 
-/* Pattern callback */
+/**
+ * Pattern callback.
+ * @param[in] pattern  The pattern itself.
+ * @param[in] v        The point at which to evaluate the pattern.
+ * @return The value of the pattern at \p v.
+ */
 typedef double dmnsn_pattern_fn(const dmnsn_pattern *pattern, dmnsn_vector v);
 
-/* Generic pattern */
+/** A pattern. */
 struct dmnsn_pattern {
-  /* Callbacks */
-  dmnsn_pattern_fn *pattern_fn;
-  dmnsn_free_fn    *free_fn;
+  dmnsn_pattern_fn *pattern_fn; /**< The pattern callback. */
+  dmnsn_free_fn    *free_fn;    /**< The destructor callback. */
 
-  /* Transformation matrix */
-  dmnsn_matrix trans, trans_inv;
+  dmnsn_matrix trans;     /**< The transformation matrix of the pattern */
+  dmnsn_matrix trans_inv; /**< The inverse of the transformation matrix */
 
-  /* Generic pointer */
-  void *ptr;
+  void *ptr; /**< Generic pointer */
 };
 
+/**
+ * Allocate an dummy pattern.
+ * @return A pattern with no callbacks set.
+ */
 dmnsn_pattern *dmnsn_new_pattern(void);
+
+/**
+ * Delete a pattern.
+ * @param[in,out] pattern  The pattern to destroy.
+ */
 void dmnsn_delete_pattern(dmnsn_pattern *pattern);
 
+/**
+ * Initialize a pattern.  This precomputes some values that are used during
+ * ray-tracing; the pattern will not work until it has been initialized, but
+ * should not be modified after it has been initialized.  Patterns are generally
+ * initialized for you.
+ * @param[in,out] pattern  The pattern to initialize.
+ */
 void dmnsn_pattern_init(dmnsn_pattern *pattern);
 
-/* Invoke the pattern callback with the right transformation */
+/**
+ * Invoke the pattern callback with the right transformation.
+ * @param[in] pattern  The pattern to evaluate.
+ * @param[in] v        The point to get the pattern value for.
+ * @return The value of the pattern at \p v.
+ */
 double dmnsn_pattern_value(const dmnsn_pattern *pattern, dmnsn_vector v);
 
 #endif /* DIMENSION_PATTERN_H */