From 81d691e66af6e4032127dfa287abdec613a0b832 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A5rd=20Skaflestad?= <Bard.Skaflestad@sintef.no>
Date: Tue, 1 Jul 2014 18:05:25 +0200
Subject: [PATCH] wells.h: Document several function

This commit adds Doxygen-style documentation to functions

  - clear_well_controls()
  - set_current_control()
  - wells_equal()

No functional changes.
---
 opm/core/wells.h | 64 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 61 insertions(+), 3 deletions(-)

diff --git a/opm/core/wells.h b/opm/core/wells.h
index 1d6b7ef2b..df23b7437 100644
--- a/opm/core/wells.h
+++ b/opm/core/wells.h
@@ -226,16 +226,38 @@ append_well_controls(enum WellControlType type  ,
                      int                  well_index,
                      struct Wells        *W);
 
+
 /**
- * Set the current control for a single well.
+ * Set the current/active control for a single well.
+ *
+ * The new control ID must refer to a previously defined control mode.
+ * Total number of defined control modes available through function
+ * well_controls_get_num().
+ *
+ * \param[in]     well_index
+ *                   Identity of particular well.  Must be in
+ *                   \code [0 .. number_of_wells - 1] \endcode.
+ *
+ * \param[in]     current_control
+ *                   Index of new control mode.
+ *
+ * \param[in,out] W  Existing set of wells.
  */
 void
 set_current_control(int well_index, int current_control, struct Wells *W);
 
+
 /**
  * Clear all controls from a single well.
  *
- * Does not affect the control set capacity. */
+ * Does not affect the control set capacity.
+ *
+ * \param[in]     well_index
+ *                   Identity of particular well.  Must be in
+ *                   \code [0 .. number_of_wells - 1] \endcode.
+ *
+ * \param[in,out] W  Existing set of wells.
+ */
 void
 clear_well_controls(int well_index, struct Wells *W);
 
@@ -264,11 +286,47 @@ destroy_wells(struct Wells *W);
 struct Wells *
 clone_wells(const struct Wells *W);
 
+
+/**
+ * Compare well structures for equality.
+ *
+ * Two sets of wells are equal if all of the following conditions hold
+ *  - They have the same number of wells
+ *
+ *  - They have the same number of completions/connections
+ *
+ *  - They specify the same number of phases
+ *
+ *  - Individual wells with corresponding well IDs have the same names
+ *    (including both being \c NULL).
+ *
+ *  - Individual wells with corresponding well IDs have the same
+ *    completions
+ *
+ *  - Individual wells with corresponding well IDs have the same well
+ *    types
+ *
+ *  - Individual wells with corresponding well IDs specify the same
+ *    reference depths
+ *
+ *  - Individual wells with corresponding well IDs have the same set
+ *    of defined and active operational constraints as determined by
+ *    function well_controls_equal()
+ *
+ * \param[in] W1      Existing set of wells.
+ * \param[in] W2      Existing set of wells.
+ *
+ * \param[in] verbose Flag for whether or not to report which
+ *                    conditions do not hold.  Use \code verbose =
+ *                    true \endcode to print transcript to \c stdout.
+ *
+ * \return Whether or not well structures \c W1 and \c W2 represent
+ * the same set of wells.
+ */
 bool
 wells_equal(const struct Wells *W1, const struct Wells *W2 , bool verbose);
 
 
-
 #ifdef __cplusplus
 }
 #endif