Add Some documentation to WellState

opm/simulators/wells/WellState.hpp

@@ -251,14 +251,22 @@ public:
     }
 
 private:
+    PhaseUsage phase_usage_;
+
+    // The wells_ variable is essentially a map of all the wells on the current
+    // process. Observe that since a well can be split over several processes a
+    // well might appear in the WellContainer on different processes.
+    WellContainer<SingleWellState> wells_;
+
+    // The members alq_state, global_well_info and well_rates are map like
+    // structures which will have entries for *all* the wells in the system.
+
     // Use of std::optional<> here is a technical crutch, the
     // WellStateFullyImplicitBlackoil class should be default constructible,
     // whereas the GlobalWellInfo is not.
     std::optional<GlobalWellInfo> global_well_info;
     ALQState alq_state;
-    PhaseUsage phase_usage_;
 
-    WellContainer<SingleWellState> wells_;
     // The well_rates variable is defined for all wells on all processors. The
     // bool in the value pair is whether the current process owns the well or
     // not.
@@ -278,12 +286,7 @@ private:
     // reset current_alq and update default_alq. ALQ is used for
     // constant lift gas injection and for gas lift optimization
     // (THP controlled wells).
-    //
-    // NOTE: If a well is no longer used (e.g. it is shut down)
-    // it is still kept in the maps "default_alq_" and "current_alq_". Since the
-    // number of unused entries should be small (negligible memory
-    // overhead) this is simpler than writing code to delete it.
-    //
+
     void updateWellsDefaultALQ(const std::vector<Well>& wells_ecl);
 
     /// Allocate and initialize if wells is non-null.