Add some documentation

- Document hvif-light.h
- Partialy document hvif-cairo.h
- Tweak Doxyfile

.gitignore

@@ -17,9 +17,13 @@ src/.dirstamp
 src/config.h*
 src/stamp-h1
 src/src
+docs/html
 
+.gdb_history
+doxyfile.stamp
 Makefile
 Makefile.in
+Doxyfile
 aclocal.m4
 autom4te.cache
 compile

Makefile.am

@@ -1 +1,2 @@
+include docs/Makefile.am
 include src/Makefile.am

configure.ac

@@ -17,10 +17,8 @@ AX_CHECK_COMPILE_FLAG([-std=c11],
     [ CFLAGS+=" -std=c11" ],
     [ AC_MSG_ERROR([C compiler doesn't support C11 mode])] )
 
-# TODO: Update checks once we have code
-
 # Checks for header files.
-AC_CHECK_HEADERS([limits.h stddef.h stdint.h stdlib.h string.h sys/time.h unistd.h])
+AC_CHECK_HEADERS([assert.h math.h stdint.h stdlib.h stdbool.h stdio.h])
 
 # Checks for typedefs, structures, and compiler characteristics.
 AC_CHECK_HEADER_STDBOOL
@@ -70,6 +68,15 @@ if test x$lto = xyes; then
 fi
 
 AC_CONFIG_FILES([Makefile src/Makefile])
+
+# Documentation
+AC_CHECK_PROGS([DOXYGEN], [doxygen])
+if test -z "$DOXYGEN";
+    then AC_MSG_WARN([Doxygen not found - continuing without Doxygen support])
+fi
+AM_CONDITIONAL([HAVE_DOXYGEN], [test -n "$DOXYGEN"])
+AM_COND_IF([HAVE_DOXYGEN], [AC_CONFIG_FILES([docs/Doxyfile])])
+
 AC_OUTPUT
 
 AS_ECHO("")

docs/Makefile.am

@@ -0,0 +1,13 @@
+if HAVE_DOXYGEN
+
+doxyfile.stamp:
+	$(DOXYGEN) $(top_builddir)/docs/Doxyfile
+	echo Timestamp > doxyfile.stamp
+
+CLEANFILES = doxyfile.stamp
+
+html-local: doxyfile.stamp
+clean-local:
+	rm -rf $(top_builddir)/docs/html
+
+endif 

shell.nix

@@ -15,6 +15,6 @@ pkgs.stdenv.mkDerivation {
   name = "hvif-light";
 
   hardeningDisable = [ "all" ];
-  buildInputs = with pkgs; [ autoconf automake gcc clang-tools gdb valgrind-light pkg-config cairo ];
+  buildInputs = with pkgs; [ autoconf automake gcc clang-tools gdb valgrind-light pkg-config cairo doxygen ];
 
 }

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
 

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 */