Merge pull request #6921 from gassmoeller/improve_variable_documentation

Improve Newton solver variable documentation

Author: tjhei

include/aspect/simulator.h

@@ -2054,18 +2054,49 @@ namespace aspect
       std::unique_ptr<LinearAlgebra::PreconditionAMG>           Amg_preconditioner;
       std::unique_ptr<LinearAlgebra::PreconditionBase>          Mp_preconditioner;
 
+      /**
+       * Whether to resize and rebuild the sparsity pattern and matrix. This can become
+       * necessary if constraints or the mesh changes.
+       */
       bool                                                      rebuild_sparsity_and_matrices;
+
+      /**
+       * Whether to assemble the stokes matrix before solving the Stokes equation.
+       * A matrix that is identical for subsequent time steps (e.g. if the viscosity is constant
+       * over time and no constraints change) can be reused and does not need to be assembled
+       * again, saving considerable computational time.
+       *
+       * Note, that this parameter does not control whether the right-hand side force term of
+       * the equation is assembled (it is always assembled).
+       *
+       * Also note that in the case of defect correction or Newton solvers, the Stokes
+       * matrix is actually on the right-hand side of the equation. The meaning of this flag
+       * does not change however, it still determines if these (right-hand) side terms are
+       * assembled.
+       */
       bool                                                      rebuild_stokes_matrix;
+
+      /**
+       * Whether to assemble the left-hand side matrix of the defect correct or Newton
+       * solver, i.e. the system Jacobian.
+       */
       bool                                                      assemble_newton_stokes_matrix;
+
+      /**
+       * A flag that indicates if we are solving a fixed point Stokes equation (if false),
+       * or a defect correction/Newton solver system (if true).
+       */
       bool                                                      assemble_newton_stokes_system;
+
+      /**
+       * Whether to assemble the stokes preconditioner matrix (if one is used).
+       */
       bool                                                      rebuild_stokes_preconditioner;
 
       /**
        * @}
        */
 
-    private:
-
       /**
        * Unique pointer for an instance of the MeshDeformationHandler. this way,
        * if we do not need the machinery for doing mesh deformation stuff, we do