From 70fa69c46506d18bbd6b0346f6a921e9a0036054 Mon Sep 17 00:00:00 2001
From: Hans-Joerg Schurr <commits@schurr.at>
Date: Tue, 5 May 2020 00:07:39 +0200
Subject: [PATCH] Add some documentation

- Document hvif-light.h
- Partialy document hvif-cairo.h
- Tweak Doxyfile
---
 .gitignore       |  1 +
 docs/Doxyfile.in |  4 ++--
 src/hvif-cairo.h | 15 ++++++++++++++
 src/hvif-light.h | 54 ++++++++++++++++++++++++++++++++++++++++--------
 4 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/.gitignore b/.gitignore
index 500ad88..9193416 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,7 @@ src/src
 docs/html
 
 .gdb_history
+doxyfile.stamp
 Makefile
 Makefile.in
 Doxyfile
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
index ecc9452..61be178 100644
--- a/docs/Doxyfile.in
+++ b/docs/Doxyfile.in
@@ -895,7 +895,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = @srcdir@/config.h
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1492,7 +1492,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
diff --git a/src/hvif-cairo.h b/src/hvif-cairo.h
index 7139188..21658e3 100644
--- a/src/hvif-cairo.h
+++ b/src/hvif-cairo.h
@@ -1,3 +1,18 @@
+/**
+ * \file hvif-cairo.h
+ * \author Hans-Jörg Schurr
+ *
+ * \brief An experimental renderer for \a hvif images based on cairo.
+ *
+ * This library provides functions for rendering \a hvif images with cairo.
+ * The rendere is incomplete and serves only as a vehicle to understand the
+ * semantic of \a hvif images. In general it only attempts to render
+ * features exposed by Icon-o-Matic. Furthermore multiple stroke transforms
+ * and contour transforms are not supported. Furthermore the colour space
+ * is not equivalent to the colour space used on Haiku. The renderer is only
+ * lightly tested and most likely contains horrible bugs.
+ */
+
 #ifndef HVIF_CAIRO_H
 #define HVIF_CAIRO_H
 
diff --git a/src/hvif-light.h b/src/hvif-light.h
index 846c626..feda95f 100644
--- a/src/hvif-light.h
+++ b/src/hvif-light.h
@@ -1,30 +1,66 @@
+/**
+ * \file hvif-light.h
+ * \author Hans-Jörg Schurr
+ *
+ * \brief Parse \a hvif images.
+ *
+ * This library provides functions for parsing Haiku Vector Icon
+ * files. The parser should be able to parse any files generated by Haiku
+ * as of April 2020. It is, however, wholly untested and should not be
+ * used. It most likely contains horrible bugs. During parsing some
+ * basic checks for consistency of the image data are performed. But
+ * not everything is checked. For example, paths might be invalid.
+ */
+
 #ifndef HVIF_LIGHT_H
 #define HVIF_LIGHT_H
 
 #include <stdbool.h>
 #include <stdio.h>
 
+/** \typedef The result of parsing an image. */
 typedef enum hvif_status
 {
-	SUCCESS = 0,
-	ERROR_EOF,
-	ERROR_NOMEM,
-	ERROR_MAGIC,
-	ERROR_STYLE,
-	ERROR_PATH,
-	ERROR_SHAPE
+	SUCCESS = 0, /**< The image has been parsed into memory. */
+	ERROR_EOF, /**< The file ended before parsing finished. */
+	ERROR_NOMEM, /**< Not enough memory could be allocated. */
+	ERROR_MAGIC, /**< The magic number of the file is wrong. */
+	ERROR_STYLE, /**< Parsing a style failed. */
+	ERROR_PATH, /**< Parsing a path failed. */
+	ERROR_SHAPE /**< Parsing a shape failed. */
 } hvif_status;
 
+/**
+ * \typedef Opaque structure to reference a parsed image.
+ * 	An API to inspect the image will be provided later.
+ */
 typedef struct hvif_image hvif_image;
 
+/**
+ * \typedef Captures the result of parsing: a status code together with the
+ * 	image.
+ */
 typedef struct hvif_result hvif_result;
 struct hvif_result
 {
-	hvif_status status;
-	hvif_image* image;
+	hvif_status status; /**< Indicates success or an error in parsing. */
+	hvif_image* image; /**< The image structure. NULL if parsing failed. */
 };
 
+/**
+ *  \brief Parses a \a hvif image from a file
+ *  \param[in] file A valid file handler
+ *  \return A `hvif_result` structure. A status other then SUCCESS indicates
+ * 		an error. In this case the image is NULL. Otherwise the image needs
+ *		to be freed. A success does not indicate that the image is renderable.
+ */
 hvif_result hvif_from_file(FILE* file);
+
+/**
+ *  \brief Frees the memory of the image datastructures.
+ *  \param[in] image An image pointer returned by a previous call to
+ *  	`hvif_from_file`. Can be NULL.
+ */
 void hvif_free(hvif_image* image);
 
 #endif /* HVIF_LIGHT_H */