Begin formatting doxygen style documentation comments

.gitignore

@@ -1,3 +1,4 @@
+doc/
 test/output/
 test/*
 !test/*.c

Makefile

@@ -63,6 +63,9 @@ libsemver.a: $(objs)
 libsemver.so: $(objs)
 	$(CC) -shared -o $@ $? $(LIBS)
 
+docs: Doxyfile $(hdrs)
+	doxygen
+
 install: install_include install_shared install_static
 
 install_include: include/semver.h
@@ -84,7 +87,7 @@ testclean:
 	$(MAKE) -C test clean
 
 clean:
-	rm -rf *.a *.so *.o
+	rm -rf *.a *.so *.o doc
 	$(MAKE) -C test clean
 
 .PHONY: all shared static clean install install_include \

include/semver.h

@@ -1,27 +1,36 @@
+/** \file semver.h
+ * \brief A Version manipulation library
+ */
 #include "epoch.h"
 #include <stdint.h>
 
-#define u128    __uint128_t
+#define u128    __uint128_t ///< A 128 bit unsigned integer
-#define U12_MAX 4096
+#define U12_MAX 4096        ///< The maximum size for semver fields
 
+/** An enumeration representing the type of versioning being used */
 typedef enum {
-    Simple,
+    Simple,   /**< A single numeric identifier, ie `Firefox 102` */
-    Rapid,
+    Rapid,    /**< A two digit versioning scheme */
-    SemVer,
+    SemVer,   /**< Ordinary `SemVer` versioning, ie `major.minor.patch` */
-    Extended,
+    Extended, /**< An extended semver type with an extra `build` field */
 } VersionKindTag;
 
+/** Represents a Git version control revision as a pre-release */
 typedef struct {
-    char     hash[7];
+    char     hash[7]; /**< The short form hash of a Git revision */
-    DateTime dt;
+    DateTime dt;      /**< The date and time of the Git revision */
 } GitRevision;
 
+/** An enumeration representing the type of pre-release, if any */
 typedef enum {
     Alpha,
     Beta,
-    ReleaseCandidate,
+    ReleaseCandidate, /**< An rc prerelease is the last stage in testing prior
-    GitRev,
+                           to a final releas */
-    PRNone,
+    GitRev,           /**< A Git version control revision used as a pre-release
+                           `preview` */
+    PRNone,           /**< Not a pre-release, or in other words a final release
+                           version */
 } PreReleaseTag;
 
 typedef enum {
@@ -41,42 +50,51 @@ typedef enum {
     x86_64,
 } Arch;
 
+/** A tagged union type storing a pre-release in one of several forms */
 typedef struct {
-    PreReleaseTag    tag;
+    PreReleaseTag    tag;   /**< The tag field specifies the type of pre-release */
     union {
-        uint16_t     alpha;
+        uint16_t     alpha; /**< The numerical component of an `Alpha` pre-release */
-        uint16_t     beta;
+        uint16_t     beta;  /**< The numerical component of a `Beta` pre-release */
-        uint16_t     rc;
+        uint16_t     rc;    /**< The numerical component of a release candidate */
-        GitRevision  git;
+        GitRevision  git;   /**< A Git version control revision as a pre-release */
     };
 } PreRelease;
 
+/** Stores all relevant information to represent several different styles of versioning */
 typedef struct {
-    VersionKindTag   vk_tag;
+    VersionKindTag   vk_tag;   /**< Specifies the type of versioning scheme being usef */
     union {
         struct {
             uint16_t major;
-        }            simple;
+        }            simple;   /**< A single number versioning scheme */
         struct {
-            uint16_t major;
+            uint16_t major;    /**< The "series" number, representing significant
-            uint16_t minor;
+                                    api changes */
-        }            rapid;
+            uint16_t minor;    /**< The api number. Any breaking change must bump
+                                    this number. */
+        }            rapid;    /**< A two number versioning scheme */
         struct {
-            uint16_t major;
+            uint16_t major;    /**< The "series" number, representing significant
-            uint16_t minor;
+                                    api changes */
-            uint16_t patch;
+            uint16_t minor;    /**< The api number. Any breaking change must bump
-        }            semver;
+                                    this number. */
+            uint16_t patch;    /**< Patches and bugfixes that do not break api */
+        }            semver;   /**< The traditional three digit semver scheme */
         struct {
             uint16_t major;
             uint16_t minor;
             uint16_t patch;
             uint16_t build;
-        }            extended;
+        }            extended; /**< An extended semver-like scheme with an extra
+                                    `build` identifier */
     };
-    PreRelease       pr;
+    PreRelease       pr;       /**< The pre-release identifier, if any */
-    Arch             arch;
+    Arch             arch;     /**< The processor architecture this package is
+                                    compiled for */
 } Version;
 
+/** Used to order Version structures */
 typedef enum {
     CompGreater,
     CompEqual,
@@ -84,8 +102,37 @@ typedef enum {
     CompNone,
 } Comparison;
 
+/**
+ * Creates a 128 bit unsigned integer from the data structure in such a way that
+ * versions can be compared and ordered. The `major` number has it's bits shifted
+ * by the furthest amount, followed by the `minor` (if it exists) and so on. The
+ * pre-release tag enum members each get their own bit, ordered in such a way that
+ * `PRNone` is considered greater than a release candidate and so on. The least
+ * significant 64 bits are taken up by the Unix timestamp of a git revision, if
+ * this is a Git pre-release
+ * ### Return values
+ * Returns the computed numerical representation
+ * \param self A `Version` struct  to be converted
+ */
 u128       u128FromVersion(Version *self);
+
+/**
+ * Compares `self` with `other` for purposes of ordering
+ * ### Return values
+ * Returns a `Comparison` enumeration value.
+ * \param self The first Version to be compared
+ * \param other The Version against which `self` will be compared
+ */
 Comparison compareVersion (Version *self, Version *other);
+
+/**
+ * Parses a Version from a string
+ * ### Return values
+ * Returns 0 on success
+ * \param self A pointer to a memory region to store this Version structure
+ * \param s The string to be parsed
+ */
 int        parseVersion   (Version *self, const char *s);
+
 char      *versionToString(Version *self);