From f2ab37c6c26bae661c2037526a507b99590c16a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A5rd=20Skaflestad?= <Bard.Skaflestad@sintef.no>
Date: Sun, 22 Apr 2012 11:50:41 +0200
Subject: [PATCH] Expand description of function create_wells().

Restore original parameter names in the process.
---
 opm/core/newwells.h         | 29 ++++++++++++++++++++++-------
 opm/core/utility/newwells.c |  6 +++---
 2 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/opm/core/newwells.h b/opm/core/newwells.h
index 829494f8..fdf8383e 100644
--- a/opm/core/newwells.h
+++ b/opm/core/newwells.h
@@ -115,15 +115,30 @@ struct CompletionData
     double *phasemob; /** Phase mobilities. */
 };
 
-/** Contruction function initializing a Wells object.
- *  The arguments may be used to indicate expected capacity needed,
- *  they will be used internally for pre-allocation.
- *  \return NULL upon failure, otherwise a valid Wells object with 0 wells.
- *  Call add_well() to populate the Wells object.
- *  Call destroy_wells() to deallocate and clean up the Wells object.
+/**
+ * Construct a Wells object initially capable of managing a given
+ * number of wells and total number of well connections
+ * (perforations).
+ *
+ * Function add_well() is used to populate the Wells object.  No
+ * reallocation occurrs in function add_well() as long as the
+ * initially indicated capacites are sufficient.  Call function
+ * destroy_wells() to dispose of the Wells object and its allocated
+ * memory resources.
+ *
+ * \param[in] nwells Expected number of wells in simulation scenario.
+ *                   Pass zero if the total number of wells is unknown.
+ *
+ * \param[in] nperf  Expected total number of well connections
+ *                   (perforations) for all wells in simulation
+ *                   scenario.  Pass zero if the total number of well
+ *                   connections is unknown.
+ *
+ * \return A valid Wells object with no wells if successful, and NULL
+ * otherwise.
  */
 struct Wells *
-create_wells(int nwells_reserve_cap, int nperf_reserve_cap);
+create_wells(int nwells, int nperf);
 
 
 /**
diff --git a/opm/core/utility/newwells.c b/opm/core/utility/newwells.c
index c241ea23..411a5a58 100644
--- a/opm/core/utility/newwells.c
+++ b/opm/core/utility/newwells.c
@@ -322,7 +322,7 @@ wells_reserve(int nwells, int nperf, struct Wells *W)
 
 /* ---------------------------------------------------------------------- */
 struct Wells *
-create_wells(int nwells_reserve_cap, int nperf_reserve_cap)
+create_wells(int nwells, int nperf)
 /* ---------------------------------------------------------------------- */
 {
     int           ok;
@@ -349,8 +349,8 @@ create_wells(int nwells_reserve_cap, int nperf_reserve_cap)
         if (ok) {
             W->well_connpos[0] = 0;
 
-            if ((nwells_reserve_cap > 0) || (nperf_reserve_cap > 0)) {
-                ok = wells_reserve(nwells_reserve_cap, nperf_reserve_cap, W);
+            if ((nwells > 0) || (nperf > 0)) {
+                ok = wells_reserve(nwells, nperf, W);
             }
         }