rearrange content for clarity

doc/examples/goal_programming.rst

@@ -96,8 +96,8 @@ this example, we demonstrate three ways to define a goal in RTC-Tools.
 
 First, we have a high priority goal to keep the water level within a minimum and
 maximum. Since we are applying this goal to a specific state (model variable) in
-our model at every time step, we can use a special helper class to define this
-goal, called a ``StateGoal``:
+our model at every time step, we can inherit a special helper class to define
+this goal, called a ``StateGoal``:
 
 .. literalinclude:: ../../examples/goal_programming/src/example.py
   :language: python
@@ -168,8 +168,11 @@ optimizer.
 
 For the goals that want to apply our goals to every timestep, so we use the
 ``path_goals()`` method. This is a method that returns a list of the path goals
-we defined above. Goals that inherit ``StateGoal`` are always path goals and
-must also always be initialized with the parameter ``self``.
+we defined above. Note that with path goals,  each timestep is implemented as
+an independant goal- if we cannot satisfy our min/max on time step A, it will
+not affect our desire to satisfy the goal at time step B. Goals that inherit
+``StateGoal`` are always path goals and must also always be initialized with the
+parameter ``self``.
 
 .. literalinclude:: ../../examples/goal_programming/src/example.py
   :language: python

examples/goal_programming/src/example.py

@@ -12,10 +12,7 @@ class WaterLevelRangeGoal(StateGoal):
     # Applying a state goal to every time step is easily done by defining a goal
     # that inherits StateGoal. StateGoal is a helper class that uses the state
     # to determine the function, function range, and function nominal
-    # automatically. This type of goal can only be used with the path_goals()
-    # method. Note that each timestep is implemented as an independant goal- if
-    # we cannot satisfy our min/max on time step A, it will not affect our
-    # desire to satisfy the goal at time step B.
+    # automatically.
     state = 'storage.HQ.H'
     # One goal can introduce a single or two constraints (min and/or max). Our
     # target water level range is 0.43 - 0.44. We might not always be able to