Reformat to add Doxygen markup where appropriate

opm/core/newwells.h

@@ -33,26 +33,38 @@
 extern "C" {
 #endif
 
-/** Well type indicates desired/expected well behaviour. */
+/**
-enum WellType         { INJECTOR, PRODUCER };
+ * Well type indicates desired/expected well behaviour.
-
-/** Type of well control equation or inequality constraint.
- *  BHP            -> Well constrained by bottom-hole pressure target.
- *  RESERVOIR_RATE -> Well constrained by reservoir volume flow rates.
- *  SURFACE_RATE   -> Well constrained by surface volume flow rates.
  */
-enum WellControlType  { BHP, RESERVOIR_RATE, SURFACE_RATE };
+enum WellType {
+    INJECTOR,  /**< Well is an injector */
+    PRODUCER   /**< Well is a producer */
+};
 
-/** Controls for a single well.
+/**
+ * Type of well control equation or inequality constraint.
+ */
+enum WellControlType  {
+    BHP,              /**< Well constrained by BHP target */
+    RESERVOIR_RATE,   /**< Well constrained by reservoir volume flow rate */
+    SURFACE_RATE      /**< Well constrained by surface volume flow rate */
+};
+
+/**
+ * Controls for a single well.
  * Each control specifies a well rate or bottom-hole pressure. Only
  * one control can be active at a time, indicated by current. The
  * meaning of each control's target value depends on the control type:
- *  BHP            -> target pressure in Pascal.
+ *
- *  RESERVOIR_RATE -> target reservoir volume rate in cubic(meter)/second
+ *  - BHP            -> target pressure in Pascal.
- *  SURFACE_RATE   -> target surface volume rate in cubic(meter)/second
+ *  - RESERVOIR_RATE -> target reservoir volume rate in cubic(meter)/second
+ *  - SURFACE_RATE   -> target surface volume rate in cubic(meter)/second
+ *
  * The sign convention for RATE targets is as follows:
- *    (+) Fluid flowing into reservoir, i.e. injecting.
+ *
- *    (-) Fluid flowing out of reservoir, i.e. producing.
+ *  - (+) Fluid flowing into reservoir, i.e. injecting.
+ *  - (-) Fluid flowing out of reservoir, i.e. producing.
+ *
  * For *_RATE controls, the distribution of phases used for the control
  * is also needed. For example, a total rate control should have 1.0
  * for each phase, whereas a control on oil rate should have 1.0 for
@@ -65,65 +77,133 @@ enum WellControlType  { BHP, RESERVOIR_RATE, SURFACE_RATE };
  */
 struct WellControls
 {
-    int                     num;     /** Number of controls. */
+    /**
-    enum WellControlType   *type;    /** Array of control types.*/
+     * Number of controls.
-    double                 *target;  /** Array of control targets */
+     */
-    double                 *distr;   /** Array of rate control distributions,
+    int num;
-                                         Wells::number_of_phases numbers per control */
-    int                     current; /** Index of current active control. */
 
-    void                   *data;    /** Internal management structure. */
+    /**
+     * Array of control types.
+     */
+    enum WellControlType *type;
+
+    /**
+     * Array of control targets
+     */
+    double *target;
+
+    /**
+     * Array of rate control distributions,
+     * <CODE>Wells::number_of_phases</CODE> numbers for each control
+     */
+    double *distr;
+
+    /**
+     * Index of current active control.
+     */
+    int current;
+
+    /**
+     * Internal management structure.
+     */
+    void *data;
 };
 
 
 
-/** Data structure aggregating static information about all wells in a scenario. */
+/**
+ *  Data structure aggregating static information about all wells in a scenario.
+ */
 struct Wells
 {
-    int                  number_of_wells;  /** Number of wells. */
+    int number_of_wells;  /**< Number of wells. */
-    int                  number_of_phases; /** Number of phases. */
+    int number_of_phases; /**< Number of phases. */
 
-    enum WellType       *type;            /** Array of well types. */
+    /**
-    double              *depth_ref;       /** Array of well bhp reference depths. */
+     * Array of well types.
-    double              *comp_frac;       /** Component fractions for each well, size is (number_of_wells*number_of_phases).
+     */
+    enum WellType *type;
+
+    /**
+     * Array of well types.
+     */
+    double *depth_ref;
+
+    /**
+     * Component fractions for each well.  Array of size
+     * <CODE>number_of_wells * number_of_phases</CODE>.
      * This is intended to be used for injection wells. For production wells
      * the component fractions will vary and cannot be specified a priori.
      */
-    int                 *well_connpos;    /** Array of indices into well_cells (and WI).
+    double *comp_frac;
-                                           *  For a well w, well_connpos[w] and well_connpos[w+1] yield
+
-                                           *  start and one-beyond-end indices into the well_cells array
+    /**
-                                           *  for accessing w's perforation cell indices.
+     * Array of indices into well_cells (and WI).  For a well @c w,
+     * <CODE>well_connpos[w]</CODE> and <CODE>well_connpos[w+1]</CODE> are start
+     * and one-beyond-end indices into the @c well_cells array for accessing
+     * @c w's perforation cell indices.
      */
-    int                 *well_cells;      /** Array of perforation cell indices.
+    int *well_connpos;
+
+    /**
+     * Array of perforation cell indices.
      * Size is number of perforations (== well_connpos[number_of_wells]).
      */
-    double              *WI;              /** Well productivity index, same size and structure as well_cells. */
+    int *well_cells;
-    struct WellControls **ctrls;          /** Well controls, one set of controls for each well. */
 
-    char                **name;           /** Well names. One string for each well. */
+    /**
+     *  Well productivity index, same size and structure as well_cells.
+     */
+    double *WI;
 
-    void               *data;             /** Internal management structure. */
+
+    /**
+     * Well controls, one set of controls for each well.
+     */
+    struct WellControls **ctrls;
+
+    /**
+     * Well names. One string for each well.
+     */
+    char **name;
+
+    /**
+     * Internal management structure.
+     */
+    void *data;
 };
 
 
-/** Data structure aggregating dynamic information about all wells in a scenario.
+/**
- *  All arrays in this structure contain data for each perforation,
+ * Data structure aggregating dynamic information about all wells in a scenario.
- *  ordered the same as Wells::well_cells and Wells:WI.  The array
+ * All arrays in this structure contain data for each perforation, ordered the
- *  sizes are, respectively,
+ * same as Wells::well_cells and Wells:WI.  The array sizes are, respectively,
  *
  *     gpot       n*NP
  *     A          n²*NP (matrix in column-major (i.e., Fortran) order).
  *     phasemob   n*NP
  *
- *  in which "n" denotes the number of active fluid phases (and
+ * in which "n" denotes the number of active fluid phases (and constituent
- *  constituent components) and "NP" is the total number of
+ * components) and "NP" is the total number of perforations,
- *  perforations, <CODE>well_connpos[ number_of_wells ]</CODE>.
+ * <CODE>well_connpos[ number_of_wells ]</CODE>.
  */
 struct CompletionData
 {
-    double *gpot;     /** Gravity potentials. */
+    /**
-    double *A;        /** Volumes to surface-components matrix, A = RB^{-1}. */
+     * Gravity potentials.
-    double *phasemob; /** Phase mobilities. */
+     */
+    double *gpot;
+
+    /**
+     * Volumes to surface-components matrix, A = RB^{-1}.
+     */
+    double *A;
+
+    /**
+     * Phase mobilities for all perforations, stored consecutively with the
+     * phase index cycling the most rapidly.
+     */
+    double *phasemob;
 };
 
 /**