Write more documentation. (Closes idaholab#7842)

framework/include/multiapps/MultiApp.h

@@ -95,10 +95,21 @@ class MultiApp : public MooseObject, public SetupInterface, public Restartable
    */
   virtual bool solveStep(Real dt, Real target_time, bool auto_advance = true) = 0;
 
-  /// Advances the time step (not the time if you can believe it)
+  /**
+   * Advances the multi-apps time step which is important for dt selection.
+   * (Note this does not advance the *time*. That is done in Transient::endStep,
+   * which is called either directly from solveStep() for loose coupling cases
+   * or through finishStep() for Picard coupling cases)
+   */
   virtual void incrementTStep() = 0;
 
-  /// Creates output
+  /**
+   * Calls multi-apps executioners' endStep and postStep methods which creates output and advances
+   * time (not the time step; see incrementTStep()) among other things. This method is only called
+   * for Picard calculations and is called *after* the master application's executioner's endStep
+   * method. Consequently Picard may not work in conjunction with restart since the sub-app's time
+   * will not have been updated before the restartable data file is written.
+   */
   virtual void finishStep() = 0;
 
   /**

framework/src/executioners/Transient.C

@@ -369,11 +369,22 @@ Transient::incrementStepOrReject()
 
       _problem.advanceState();
 
+      /*
+       * Call the multi-app executioners endStep and
+       * postStep methods when doing Picard. We do not perform these calls for
+       * loose coupling because Transient::endStep and Transient::postStep get
+       * called from TransientMultiApp::solveStep in that case.
+       */
       if (_picard_max_its > 1)
       {
         _problem.finishMultiAppStep(EXEC_TIMESTEP_BEGIN);
         _problem.finishMultiAppStep(EXEC_TIMESTEP_END);
       }
+      /*
+       * Ensure that we increment the sub-application time steps so that
+       * when dt selection is made in the master application, we are using
+       * the correct time step information
+       */
       _problem.incrementMultiAppTStep(EXEC_TIMESTEP_BEGIN);
       _problem.incrementMultiAppTStep(EXEC_TIMESTEP_END);
     }