From: Florian Forster <octo@leeloo.lan.home.verplant.org>
Date: Mon, 17 May 2010 08:49:12 +0000 (+0200)
Subject: src/sn_stage.h: Begin adding Doxygen documentation.
X-Git-Tag: v1.0.0~39
X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=aedb88c4afbb1af275eb8b5a04ade11528062b28;p=sort-networks.git

src/sn_stage.h: Begin adding Doxygen documentation.
---

diff --git a/src/sn_stage.h b/src/sn_stage.h
index 192887a..e2b57a6 100644
--- a/src/sn_stage.h
+++ b/src/sn_stage.h
@@ -31,47 +31,128 @@
 
 #include "sn_comparator.h"
 
+/**
+ * Struct representing a stage of the comparator network. Don't modify this
+ * struct yourself, use the sn_stage_* methods instead.
+ */
 struct sn_stage_s
 {
-  int depth;
-  sn_comparator_t *comparators;
-  int comparators_num;
+  int depth;                    /**< Depth of this stage, where zero means closest to the input. */
+  sn_comparator_t *comparators; /**< Pointer to a list of comparators contained in this stage. */
+  int comparators_num;          /**< Number of comparators in this stage. */
 };
 typedef struct sn_stage_s sn_stage_t;
 
+/**
+ * Direction into which to cut.
+ *
+ * \see sn_network_cut_at, sn_stage_cut_at
+ */
 enum sn_network_cut_dir_e
 {
-  DIR_MIN,
-  DIR_MAX
+  DIR_MIN, /**< Assume negative infinity. */
+  DIR_MAX  /**< Assume positive infinity. */
 };
 
 #define SN_STAGE_DEPTH(s) (s)->depth
 #define SN_STAGE_COMP_NUM(s) (s)->comparators_num
 #define SN_STAGE_COMP_GET(s,n) ((s)->comparators + (n))
 
+/**
+ * Creates an empty stage and returns a pointer to it. The stage must be freed
+ * using sn_stage_destroy().
+ *
+ * \param depth Depth of the stage within the comparator network. This will be
+ *   re-set by sn_network_stage_add().
+ * \return Pointer to the comparator network or \c NULL on error.
+ */
 sn_stage_t *sn_stage_create (int depth);
 
 /**
  * Clones an existing stage.
  *
  * \param s Stage to clone.
- * \return Copied stage or NULL on error. The returned stage must be freed
+ * \return Copied stage or \c NULL on error. The returned stage must be freed
  *   using sn_stage_destroy().
  */
 sn_stage_t *sn_stage_clone (const sn_stage_t *s);
+
+/**
+ * Destroys a stage allocated with sn_stage_create() or one of the other
+ * methods returning a \c sn_stage_t. This frees all allocated space.
+ *
+ * \param s The stage to destroy. May be \c NULL.
+ */
 void sn_stage_destroy (sn_stage_t *s);
 
+/**
+ * Applies a stage to an array of integers.
+ *
+ * \param s Pointer to the stage.
+ * \param[in,out] values Pointer to integer values to sort. The number of
+ *   integer values pointed to must be at least the number of inputs of the
+ *   comparator network. Otherwise, segmentation faults or memory corruption
+ *   will occur.
+ * \return Zero on success, non-zero on failure.
+ * \see sn_network_sort
+ */
 int sn_stage_sort (sn_stage_t *s, int *values);
 
+/**
+ * Adds a comparator to a stage. If this would return in a conflict (a
+ * comparator using on of the line already exists in this stage) an error is
+ * returned.
+ *
+ * \param s Pointer to the stage.
+ * \param c Pointer to a comparator to add. The given comparator is copied. It
+ *   is the caller's responsibility to free c.
+ * \return Zero on success, non-zero on failure.
+ * \see sn_stage_comparator_remove
+ */
 int sn_stage_comparator_add (sn_stage_t *s, const sn_comparator_t *c);
-int sn_stage_comparator_remove (sn_stage_t *s, int c_num);
+
+
+/**
+ * Removed a comparator from a stage.
+ *
+ * \param s The stage from which to remove the comparator.
+ * \param index The index of the comparator to remove.
+ * \return Zero on success, non-zero on failure.
+ * \see sn_stage_comparator_add
+ */
+int sn_stage_comparator_remove (sn_stage_t *s, int index);
+
+/**
+ * Checks whether the given comparator can be added to a stage, i.e. if neither
+ * line if used by another comparator.
+ *
+ * \param s Pointer to the stage.
+ * \param c Pointer to the comparator.
+ * \return Zero if there is no conflict, one if there is a conflict and two if
+ *   the comparator is already present in the stage.
+ */
 int sn_stage_comparator_check_conflict (sn_stage_t *s, const sn_comparator_t *c);
 
 int sn_stage_show (sn_stage_t *s);
 int sn_stage_invert (sn_stage_t *s);
 int sn_stage_shift (sn_stage_t *s, int sw, int inputs_num);
 int sn_stage_swap (sn_stage_t *s, int con0, int con1);
+
+/**
+ * Removes an input / line by assuming positive or negative infinity is applied
+ * to one line.
+ *
+ * \param s The stage to work with.
+ * \param input The input / line on which is assumed to be positive or negative
+ *   infinity.
+ * \param dir Direction in which to cut; whether positive or negative infinity
+ *   is assumed.
+ * \return The new position of the infinite value on success or less than zero
+ *   on failure.
+ * \see sn_network_cut_at
+ */
 int sn_stage_cut_at (sn_stage_t *s, int input, enum sn_network_cut_dir_e dir);
+
 int sn_stage_remove_input (sn_stage_t *s, int input);
 
 sn_stage_t *sn_stage_read (FILE *fh);