Document libdimension with Doxygen.

1 files changed, 33 insertions, 5 deletions

diff --git a/libdimension/dimension/finishes.h b/libdimension/dimension/finishes.h
index b84b5fb..bc07759 100644
--- a/libdimension/dimension/finishes.h
+++ b/libdimension/dimension/finishes.h
@@ -18,23 +18,51 @@
  * <http://www.gnu.org/licenses/>.                                       *
  *************************************************************************/
 
-/*
- * Custom finishes.
+/**
+ * @file
+ * Pre-defined finishes.
  */
 
 #ifndef DIMENSION_FINISHES_H
 #define DIMENSION_FINISHES_H
 
-/* Add two finishes */
+/**
+ * Add two finishes together.
+ * @param[in,out] f1  The first finish.
+ * @param[in,out] f2  The second finish.
+ * @return A finish that adds the values of two finishes together.
+ */
 dmnsn_finish *dmnsn_new_finish_combination(dmnsn_finish *f1, dmnsn_finish *f2);
 
+/**
+ * Ambient finish.
+ * @param[in] ambient  The color of the ambient light.
+ * @return A finish with ambient light.
+ */
 dmnsn_finish *dmnsn_new_ambient_finish(dmnsn_color ambient);
+
+/**
+ * Diffuse finish.
+ * @param[in] diffuse  The diffuse reflection coefficient.
+ * @return A finish with diffuse reflection.
+ */
 dmnsn_finish *dmnsn_new_diffuse_finish(double diffuse);
 
-/* A phong specular highlight */
+/**
+ * A phong specular highlight.
+ * @param[in] specular  The specular reflection coefficient.
+ * @param[in] exp       The exponent (roughly the highlight size).
+ * @return A finish with phong specular highlight.
+ */
 dmnsn_finish *dmnsn_new_phong_finish(double specular, double exp);
 
-/* Specular reflection */
+/**
+ * Specular (mirror) reflection.
+ * @param[in] min      Reflection at paralell angles.
+ * @param[in] max      Reflection at perpendicular angles (often == \p min).
+ * @param[in] falloff  Degree of exponential falloff (usually 1).
+ * @return A finish with specular reflection.
+ */
 dmnsn_finish *dmnsn_new_reflective_finish(dmnsn_color min, dmnsn_color max,
                                           double falloff);