From db9c59d0b8c87dce7c2dd3e409c8c5c844d1f2e6 Mon Sep 17 00:00:00 2001
From: Florian Forster <octo@leeloo.lan.home.verplant.org>
Date: Wed, 19 May 2010 17:59:17 +0200
Subject: [PATCH] src/sn_comparator.h: Add Doxygen documentation.

---
 src/sn_comparator.c |  6 ++---
 src/sn_comparator.h | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/src/sn_comparator.c b/src/sn_comparator.c
index 4176c7c..18361e4 100644
--- a/src/sn_comparator.c
+++ b/src/sn_comparator.c
@@ -88,11 +88,9 @@ void sn_comparator_swap (sn_comparator_t *c, int con0, int con1)
   }
 } /* void sn_comparator_swap */
 
-int sn_comparator_compare (const void *v0, const void *v1)
+int sn_comparator_compare (const sn_comparator_t *c0,
+    const sn_comparator_t *c1)
 {
-  sn_comparator_t *c0 = (sn_comparator_t *) v0;
-  sn_comparator_t *c1 = (sn_comparator_t *) v1;
-
   if (SN_COMP_LEFT (c0) < SN_COMP_LEFT (c1))
     return (-1);
   else if (SN_COMP_LEFT (c0) > SN_COMP_LEFT (c1))
diff --git a/src/sn_comparator.h b/src/sn_comparator.h
index 09c2b57..db46982 100644
--- a/src/sn_comparator.h
+++ b/src/sn_comparator.h
@@ -27,25 +27,84 @@
 #ifndef SN_COMPARATOR_H
 #define SN_COMPARATOR_H 1
 
+/**
+ * Struct representing a comparator. Don't access the members of this struct
+ * directly, use the macros below instead.
+ */
 struct sn_comparator_s
 {
-  int min;
-  int max;
+  int min; /**< Index of the line onto which the smaller element will be put. */
+  int max; /**< Index of the line onto which the larger element will be put. */
 };
 typedef struct sn_comparator_s sn_comparator_t;
 
+/** Returns the "left" line, i.e. the line with the smaller index. */
 #define SN_COMP_LEFT(c)  (((c)->min < (c)->max) ? (c)->min : (c)->max)
+/** Returns the "right" line, i.e. the line with the larger index. */
 #define SN_COMP_RIGHT(c) (((c)->min > (c)->max) ? (c)->min : (c)->max)
+/** Returns the index of the line onto which the smaller element will be put. */
 #define SN_COMP_MIN(c) (c)->min
+/** Returns the index of the line onto which the larger element will be put. */
 #define SN_COMP_MAX(c) (c)->max
 
+/**
+ * Allocates, initializes and returns a new comparator object. The returned
+ * pointer must be freed by sn_comparator_destroy().
+ *
+ * \param min Index of the line onto which the smaller element will be put.
+ * \param max Index of the line onto which the larger element will be put.
+ * \return The newly allocated object or \c NULL on failure.
+ */
 sn_comparator_t *sn_comparator_create (int min, int max);
+
+/**
+ * Destroys a comparator object, freeing all allocated space.
+ *
+ * \param c Pointer to the comparator object. This pointer must be allocated by
+ *   sn_comparator_create().
+ */
 void sn_comparator_destroy (sn_comparator_t *c);
+
+/**
+ * Inverts a comparator by switching the minimum and maximum indexes stored in
+ * the comparator.
+ *
+ * \param c Pointer to the comparator.
+ */
 void sn_comparator_invert (sn_comparator_t *c);
+
+/**
+ * Shifts the indexes stored in the comparator by a constant offset. If the
+ * index becomes too large, it will "wrap around".
+ *
+ * \param c The comparator to modify.
+ * \param sw The offset by which to shift the indexes.
+ * \param inputs_num The number of lines / inputs of the comparator network.
+ *   This number is used to wrap large indexes around.
+ */
 void sn_comparator_shift (sn_comparator_t *c, int sw, int inputs_num);
+
+/**
+ * Swaps two line indexes by replacing all occurrences of one index with
+ * another index and vice versa. If the comparator does not touch either line,
+ * this is a no-op.
+ *
+ * \param c The comparator to modify.
+ * \param con0 Index of the first line.
+ * \param con1 Index of the second line.
+ */
 void sn_comparator_swap (sn_comparator_t *c, int con0, int con1);
 
-int sn_comparator_compare (const void *, const void *);
+/**
+ * Compares two comparators and returns less than zero, zero, or greater than
+ * zero if the first comparator is smaller than, equal to or larger than the
+ * second comparator, respectively.
+ *
+ * \param c0 Pointer to the first comparator.
+ * \param c1 Pointer to the second comparator.
+ */
+int sn_comparator_compare (const sn_comparator_t *c0,
+    const sn_comparator_t *c1);
 
 #endif /* SN_COMPARATOR_H */
 
-- 
2.11.0