From 9f9a12721a109c157ed7db4d9401e51771d4da61 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@colostate.edu>
Date: Thu, 7 Dec 2017 16:56:36 -0700
Subject: [PATCH] Fix grammar issues.

---
 include/deal.II/base/convergence_table.h      |  8 +++---
 include/deal.II/base/index_set.h              | 14 +++++-----
 include/deal.II/base/partitioner.h            | 22 +++++++--------
 include/deal.II/base/patterns.h               | 20 ++++++-------
 include/deal.II/base/polynomials_piecewise.h  |  4 +--
 include/deal.II/base/table_handler.h          |  8 +++---
 .../deal.II/base/tensor_product_polynomials.h |  2 +-
 include/deal.II/base/thread_management.h      |  4 +--
 include/deal.II/base/utilities.h              |  2 +-
 include/deal.II/fe/fe_bernstein.h             |  6 ++--
 include/deal.II/fe/fe_dgq.h                   |  9 +++---
 include/deal.II/fe/fe_q_base.h                |  2 +-
 include/deal.II/fe/fe_tools.h                 |  2 +-
 include/deal.II/fe/mapping.h                  |  4 +--
 include/deal.II/fe/mapping_cartesian.h        |  2 +-
 include/deal.II/fe/mapping_fe_field.h         |  4 ++-
 include/deal.II/fe/mapping_q_eulerian.h       |  4 +--
 include/deal.II/lac/petsc_precondition.h      | 28 +++++++++----------
 .../deal.II/multigrid/mg_transfer_internal.h  | 15 +++++-----
 .../multigrid/mg_transfer_matrix_free.h       | 18 ++++++------
 include/deal.II/sundials/kinsol.h             | 16 +++++------
 21 files changed, 98 insertions(+), 96 deletions(-)

diff --git a/include/deal.II/base/convergence_table.h b/include/deal.II/base/convergence_table.h
index 58b396adb4..f15fdf79c6 100644
--- a/include/deal.II/base/convergence_table.h
+++ b/include/deal.II/base/convergence_table.h
@@ -88,7 +88,7 @@ public:
   };
 
   /**
-   * Evaluates the convergence rates of the data column
+   * Evaluate the convergence rates of the data column
    * <tt>data_column_key</tt> due to the #RateMode in relation to the
    * reference column <tt>reference_column_key</tt>. Be sure that the value
    * types of the table entries of the data column and the reference data
@@ -137,7 +137,7 @@ public:
 
 
   /**
-   * Evaluates the convergence rates of the data column
+   * Evaluate the convergence rates of the data column
    * <tt>data_column_key</tt> due to the #RateMode.  Be sure that the value
    * types of the table entries of the data column is a number, i.e. double,
    * float, (unsigned) int, and so on.
@@ -167,7 +167,7 @@ public:
   omit_column_from_convergence_rate_evaluation(const std::string &key);
 
   /**
-   * Evaluates convergence rates due to the <tt>rate_mode</tt> in relation to
+   * Evaluate convergence rates due to the <tt>rate_mode</tt> in relation to
    * the reference column <tt>reference_column_key</tt>. This function
    * evaluates the rates of ALL columns except of the columns that are to be
    * omitted (see previous function) and except of the columns that are
@@ -185,7 +185,7 @@ public:
                                  const RateMode     rate_mode);
 
   /**
-   * Evaluates convergence rates due to the <tt>rate_mode</tt>. This function
+   * Evaluate convergence rates due to the <tt>rate_mode</tt>. This function
    * evaluates the rates of ALL columns except of the columns that are to be
    * omitted (see previous function) and except of the columns that are
    * previously evaluated rate columns.  This function allows to evaluate the
diff --git a/include/deal.II/base/index_set.h b/include/deal.II/base/index_set.h
index c3d04aed86..c101746ad2 100644
--- a/include/deal.II/base/index_set.h
+++ b/include/deal.II/base/index_set.h
@@ -314,26 +314,26 @@ public:
                      const size_type end) const;
 
   /**
-   * Removes all elements contained in @p other from this set. In other words,
+   * Remove all elements contained in @p other from this set. In other words,
    * if $x$ is the current object and $o$ the argument, then we compute $x
    * \leftarrow x \backslash o$.
    */
   void subtract_set (const IndexSet &other);
 
   /**
-   * Removes and returns the last element of the last range.
-   * Throws an exception if the IndexSet is empty.
+   * Remove and return the last element of the last range.
+   * This function throws an exception if the IndexSet is empty.
    */
   size_type pop_back ();
 
   /**
-   * Removes and returns the first element of the first range.
-   * Throws an exception if the IndexSet is empty.
+   * Remove and return the first element of the first range.
+   * This function throws an exception if the IndexSet is empty.
    */
   size_type pop_front ();
 
   /**
-   * Fills the given vector with all indices contained in this IndexSet.
+   * Fill the given vector with all indices contained in this IndexSet.
    */
   void fill_index_vector(std::vector<size_type> &indices) const;
 
@@ -353,7 +353,7 @@ public:
   void fill_binary_vector (VectorType &vector) const;
 
   /**
-   * Outputs a text representation of this IndexSet to the given stream. Used
+   * Output a text representation of this IndexSet to the given stream. Used
    * for testing.
    */
   template <class StreamType>
diff --git a/include/deal.II/base/partitioner.h b/include/deal.II/base/partitioner.h
index 07d207bbcf..30110be5e0 100644
--- a/include/deal.II/base/partitioner.h
+++ b/include/deal.II/base/partitioner.h
@@ -165,7 +165,7 @@ namespace Utilities
       void set_owned_indices (const IndexSet &locally_owned_indices);
 
       /**
-       * Allows to set the ghost indices after the constructor has been
+       * Set the ghost indices after the constructor has been
        * called.
        *
        * The optional parameter @p larger_ghost_index_set allows defining an
@@ -359,7 +359,7 @@ namespace Utilities
 
 #ifdef DEAL_II_WITH_MPI
       /**
-       * Starts the exports of the data in a locally owned array to the range
+       * Start the exports of the data in a locally owned array to the range
        * described by the ghost indices of this class.
        *
        * @param communication_channel Sets an offset to the MPI_Isend and
@@ -423,7 +423,7 @@ namespace Utilities
                                      std::vector<MPI_Request> &requests) const;
 
       /**
-       * Starts importing the data on an array indexed by the ghost indices of
+       * Start importing the data on an array indexed by the ghost indices of
        * this class that is later accumulated into a locally owned array with
        * import_from_ghosted_array_finish().
        *
@@ -467,7 +467,7 @@ namespace Utilities
                                       std::vector<MPI_Request>     &requests) const;
 
       /**
-       * Finishes importing the data from an array indexed by the ghost
+       * Finish importing the data from an array indexed by the ghost
        * indices of this class into a specified locally owned array, combining
        * the results according to the given input @p vector_operation.
        *
@@ -561,13 +561,13 @@ namespace Utilities
       IndexSet ghost_indices_data;
 
       /**
-       * Caches the number of ghost indices. It would be expensive to use @p
+       * A variable caching the number of ghost indices. It would be expensive to use @p
        * ghost_indices.n_elements() to compute this.
        */
       unsigned int n_ghost_indices_data;
 
       /**
-       * Contains information which processors my ghost indices belong to and
+       * An array that contains information which processors my ghost indices belong to and
        * how many those indices are
        */
       std::vector<std::pair<unsigned int, unsigned int> > ghost_targets_data;
@@ -581,7 +581,7 @@ namespace Utilities
       std::vector<std::pair<unsigned int, unsigned int> > import_indices_data;
 
       /**
-       * Caches the number of ghost indices. It would be expensive to compute
+       * A variable caching the number of ghost indices. It would be expensive to compute
        * it by iterating over the import indices and accumulate them.
        */
       unsigned int n_import_indices_data;
@@ -593,19 +593,19 @@ namespace Utilities
       std::vector<std::pair<unsigned int, unsigned int> > import_targets_data;
 
       /**
-       * Caches the number of chunks in the import indices per MPI rank. The
+       * An array that caches the number of chunks in the import indices per MPI rank. The
        * length is import_indices_data.size()+1.
        */
       std::vector<unsigned int> import_indices_chunks_by_rank_data;
 
       /**
-       * Caches the number of ghost indices in a larger set of indices given by
+       * A variable caching the number of ghost indices in a larger set of indices given by
        * the optional argument to set_ghost_indices().
        */
       unsigned int n_ghost_indices_in_larger_set;
 
       /**
-       * Caches the number of chunks in the import indices per MPI rank. The
+       * An array that caches the number of chunks in the import indices per MPI rank. The
        * length is ghost_indices_subset_data.size()+1.
        */
       std::vector<unsigned int> ghost_indices_subset_chunks_by_rank_data;
@@ -633,7 +633,7 @@ namespace Utilities
       MPI_Comm communicator;
 
       /**
-       * Stores whether the ghost indices have been explicitly set.
+       * A variable storing whether the ghost indices have been explicitly set.
        */
       bool have_ghost_indices;
     };
diff --git a/include/deal.II/base/patterns.h b/include/deal.II/base/patterns.h
index 886eca3a27..4511f254eb 100644
--- a/include/deal.II/base/patterns.h
+++ b/include/deal.II/base/patterns.h
@@ -223,7 +223,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -391,7 +391,7 @@ namespace Patterns
     std::size_t memory_consumption () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -477,7 +477,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -594,7 +594,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -801,7 +801,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -880,7 +880,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -944,7 +944,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -989,7 +989,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -1067,7 +1067,7 @@ namespace Patterns
     FileType  file_type;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
@@ -1121,7 +1121,7 @@ namespace Patterns
     virtual std::unique_ptr<PatternBase> clone () const;
 
     /**
-     * Creates new object if the start of description matches
+     * Create a new object if the start of description matches
      * description_init.  Ownership of that object is transferred to the
      * caller of this function.
      */
diff --git a/include/deal.II/base/polynomials_piecewise.h b/include/deal.II/base/polynomials_piecewise.h
index 02b9faf1b5..004333e2f6 100644
--- a/include/deal.II/base/polynomials_piecewise.h
+++ b/include/deal.II/base/polynomials_piecewise.h
@@ -137,12 +137,12 @@ namespace Polynomials
     Polynomial<number> polynomial;
 
     /**
-     * Stores the number of intervals that the unit interval is divided into.
+     * A variable storing the number of intervals that the unit interval is divided into.
      */
     unsigned int n_intervals;
 
     /**
-     * Stores the index of the current polynomial in the range of intervals.
+     * A variable storing the index of the current polynomial in the range of intervals.
      */
     unsigned int interval;
 
diff --git a/include/deal.II/base/table_handler.h b/include/deal.II/base/table_handler.h
index 025f675ea9..c2ca646a52 100644
--- a/include/deal.II/base/table_handler.h
+++ b/include/deal.II/base/table_handler.h
@@ -679,14 +679,14 @@ protected:
   unsigned int n_rows() const;
 
   /**
-   * Stores the column and supercolumn keys in the order desired by the user.
+   * A variable storing the column and supercolumn keys in the order desired by the user.
    * By default this is the order of adding the columns. This order may be
    * changed by set_column_order().
    */
   std::vector<std::string> column_order;
 
   /**
-   * Maps the column keys to the columns (not supercolumns).
+   * A map from the column keys to the columns (not supercolumns).
    *
    * The field is declared mutable so that the write_text() and write_tex()
    * functions can be const, even though they may pad columns below if
@@ -695,7 +695,7 @@ protected:
   mutable std::map<std::string,Column> columns;
 
   /**
-   * Maps each supercolumn key to the keys of its subcolumns in the right
+   * A map from each supercolumn key to the keys of its subcolumns in the right
    * order.  It is allowed that a supercolumn has got the same key as a
    * column.
    *
@@ -705,7 +705,7 @@ protected:
   std::map<std::string, std::vector<std::string> > supercolumns;
 
   /**
-   * Maps the supercolumn keys to the captions of the supercolumns that are
+   * A map from the supercolumn keys to the captions of the supercolumns that are
    * used in tex output.
    *
    * By default these are just the supercolumn keys but they may be changed by
diff --git a/include/deal.II/base/tensor_product_polynomials.h b/include/deal.II/base/tensor_product_polynomials.h
index cc6160b1bb..597adeaf30 100644
--- a/include/deal.II/base/tensor_product_polynomials.h
+++ b/include/deal.II/base/tensor_product_polynomials.h
@@ -80,7 +80,7 @@ public:
   TensorProductPolynomials (const std::vector<Pol> &pols);
 
   /**
-   * Prints the list of the indices to <tt>out</tt>.
+   * Print the list of the indices to <tt>out</tt>.
    */
   void output_indices(std::ostream &out) const;
 
diff --git a/include/deal.II/base/thread_management.h b/include/deal.II/base/thread_management.h
index 10a52eb38c..2cc1fccbc5 100644
--- a/include/deal.II/base/thread_management.h
+++ b/include/deal.II/base/thread_management.h
@@ -1857,7 +1857,7 @@ namespace Threads
 
 
   /**
-   * Overloads of the non-const new_task function.
+   * Overload of the non-const new_task function.
    *
    * @ingroup threads
    */
@@ -1876,7 +1876,7 @@ namespace Threads
 
 #ifndef DEAL_II_CONST_MEMBER_DEDUCTION_BUG
   /**
-   * Overloads of the new_task function.
+   * Overload of the new_task function.
    *
    * @ingroup threads
    */
diff --git a/include/deal.II/base/utilities.h b/include/deal.II/base/utilities.h
index 9aef3ed0fe..e1b091e798 100644
--- a/include/deal.II/base/utilities.h
+++ b/include/deal.II/base/utilities.h
@@ -463,7 +463,7 @@ namespace Utilities
 
 
     /**
-     * Fills the @p stats structure with information about the memory
+     * Fill the @p stats structure with information about the memory
      * consumption of this process. This is only implemented on Linux.
      */
     void get_memory_stats (MemoryStats &stats);
diff --git a/include/deal.II/fe/fe_bernstein.h b/include/deal.II/fe/fe_bernstein.h
index e1f82416df..036782436d 100644
--- a/include/deal.II/fe/fe_bernstein.h
+++ b/include/deal.II/fe/fe_bernstein.h
@@ -75,7 +75,7 @@ public:
    * this element from defining an interpolation matrix. An exception will be
    * thrown.
    *
-   * Overrides the implementation from FE_Q_Base.
+   * This function overrides the implementation from FE_Q_Base.
    */
   virtual void
   get_interpolation_matrix (const FiniteElement<dim,spacedim> &source,
@@ -86,7 +86,7 @@ public:
    * this element from defining a restriction matrix. An exception will be
    * thrown.
    *
-   * Overrides the implementation from FE_Q_Base.
+   * This function overrides the implementation from FE_Q_Base.
    */
   virtual const FullMatrix<double> &
   get_restriction_matrix (const unsigned int child,
@@ -97,7 +97,7 @@ public:
    * this element from defining a prolongation matrix. An exception will be
    * thrown.
    *
-   * Overrides the implementation from FE_Q_Base.
+   * This function overrides the implementation from FE_Q_Base.
    */
   virtual const FullMatrix<double> &
   get_prolongation_matrix (const unsigned int child,
diff --git a/include/deal.II/fe/fe_dgq.h b/include/deal.II/fe/fe_dgq.h
index d83f3a8544..e8c832e183 100644
--- a/include/deal.II/fe/fe_dgq.h
+++ b/include/deal.II/fe/fe_dgq.h
@@ -349,9 +349,10 @@ private:
   /**
    * Compute renumbering for rotation of degrees of freedom.
    *
-   * Rotates a tensor product numbering of degrees of freedom by 90 degrees.
-   * It is used to compute the transfer matrices of the children by using only
-   * the matrix for the first child.
+   * This function rotates a tensor product numbering of degrees of
+   * freedom by 90 degrees.  It is used to compute the transfer
+   * matrices of the children by using only the matrix for the first
+   * child.
    *
    * The direction parameter determines the type of rotation. It is one
    * character of @p xXyYzZ. The character determines the axis of rotation,
@@ -375,7 +376,7 @@ private:
   template <int dim1, int spacedim1> friend class FE_DGQ;
 
   /**
-   * Allows @p MappingQ class to access to build_renumbering function.
+   * Allow @p MappingQ class to access to build_renumbering function.
    */
   template <int dim1, int spacedim1> friend class MappingQ;
 };
diff --git a/include/deal.II/fe/fe_q_base.h b/include/deal.II/fe/fe_q_base.h
index b119937872..afb7747b7c 100644
--- a/include/deal.II/fe/fe_q_base.h
+++ b/include/deal.II/fe/fe_q_base.h
@@ -288,7 +288,7 @@ protected:
   static std::vector<unsigned int> get_dpo_vector(const unsigned int degree);
 
   /**
-   * Performs the initialization of the element based on 1D support points,
+   * Perform the initialization of the element based on 1D support points,
    * i.e., sets renumbering, initializes unit support points, initializes
    * constraints as well as restriction and prolongation matrices.
    */
diff --git a/include/deal.II/fe/fe_tools.h b/include/deal.II/fe/fe_tools.h
index 5dadfb5687..f4017d89cc 100644
--- a/include/deal.II/fe/fe_tools.h
+++ b/include/deal.II/fe/fe_tools.h
@@ -409,7 +409,7 @@ namespace FETools
     const bool isotropic_only = false);
 
   /**
-   * Projects scalar data defined in quadrature points to a finite element
+   * Project scalar data defined in quadrature points to a finite element
    * space on a single cell.
    *
    * What this function does is the following: assume that there is scalar
diff --git a/include/deal.II/fe/mapping.h b/include/deal.II/fe/mapping.h
index 3b8ef0b3d3..381b3c4558 100644
--- a/include/deal.II/fe/mapping.h
+++ b/include/deal.II/fe/mapping.h
@@ -343,7 +343,7 @@ public:
    */
 
   /**
-   * Maps the point @p p on the unit cell to the corresponding point on the
+   * Map the point @p p on the unit cell to the corresponding point on the
    * real cell @p cell.
    *
    * @param cell Iterator to the cell that will be used to define the mapping.
@@ -359,7 +359,7 @@ public:
                                const Point<dim>                                          &p) const = 0;
 
   /**
-   * Maps the point @p p on the real @p cell to the corresponding point on the
+   * Map the point @p p on the real @p cell to the corresponding point on the
    * unit cell, and return its coordinates. This function provides the inverse
    * of the mapping provided by transform_unit_to_real_cell().
    *
diff --git a/include/deal.II/fe/mapping_cartesian.h b/include/deal.II/fe/mapping_cartesian.h
index 1742c00f96..9e8765882f 100644
--- a/include/deal.II/fe/mapping_cartesian.h
+++ b/include/deal.II/fe/mapping_cartesian.h
@@ -67,7 +67,7 @@ public:
   Mapping<dim, spacedim> *clone () const;
 
   /**
-   * Always returns @p true because MappingCartesian preserves vertex
+   * Return @p true because MappingCartesian preserves vertex
    * locations.
    */
   bool preserves_vertex_locations () const;
diff --git a/include/deal.II/fe/mapping_fe_field.h b/include/deal.II/fe/mapping_fe_field.h
index 16787db37b..95fb0938ec 100644
--- a/include/deal.II/fe/mapping_fe_field.h
+++ b/include/deal.II/fe/mapping_fe_field.h
@@ -128,7 +128,9 @@ public:
 
 
   /**
-   * Always returns @p false.
+   * See the documentation of Mapping::preserves_vertex_locations()
+   * for the purpose of this function. The implementation in this
+   * class always returns @p false.
    */
   virtual
   bool preserves_vertex_locations () const;
diff --git a/include/deal.II/fe/mapping_q_eulerian.h b/include/deal.II/fe/mapping_q_eulerian.h
index 1b3117f153..43e7e90d88 100644
--- a/include/deal.II/fe/mapping_q_eulerian.h
+++ b/include/deal.II/fe/mapping_q_eulerian.h
@@ -129,7 +129,7 @@ public:
   Mapping<dim,spacedim> *clone () const;
 
   /**
-   * Always returns @p false because MappingQEulerian does not in general
+   * Always return @p false because MappingQEulerian does not in general
    * preserve vertex locations (unless the translation vector happens to
    * provide zero displacements at vertex locations).
    */
@@ -212,7 +212,7 @@ private:
     compute_mapping_support_points(const typename Triangulation<dim,spacedim>::cell_iterator &cell) const;
 
     /**
-     * Always returns @p false because MappingQEulerianGeneric does not in general
+     * Always return @p false because MappingQEulerianGeneric does not in general
      * preserve vertex locations (unless the translation vector happens to
      * provide for zero displacements at vertex locations).
      */
diff --git a/include/deal.II/lac/petsc_precondition.h b/include/deal.II/lac/petsc_precondition.h
index 720bbe168c..954d55ce30 100644
--- a/include/deal.II/lac/petsc_precondition.h
+++ b/include/deal.II/lac/petsc_precondition.h
@@ -159,7 +159,7 @@ namespace PETScWrappers
                         const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -174,7 +174,7 @@ namespace PETScWrappers
     AdditionalData additional_data;
 
     /**
-     * Initializes the preconditioner object without knowing a particular
+     * Initialize the preconditioner object without knowing a particular
      * matrix. This function sets up appropriate parameters to the underlying
      * PETSc object after it has been created.
      */
@@ -233,7 +233,7 @@ namespace PETScWrappers
 
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -248,7 +248,7 @@ namespace PETScWrappers
     AdditionalData additional_data;
 
     /**
-     * Initializes the preconditioner object without knowing a particular
+     * Initialize the preconditioner object without knowing a particular
      * matrix. This function sets up appropriate parameters to the underlying
      * PETSc object after it has been created.
      */
@@ -301,7 +301,7 @@ namespace PETScWrappers
                      const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -361,7 +361,7 @@ namespace PETScWrappers
                       const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -424,7 +424,7 @@ namespace PETScWrappers
                            const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -484,7 +484,7 @@ namespace PETScWrappers
                      const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -544,7 +544,7 @@ namespace PETScWrappers
                      const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -626,7 +626,7 @@ namespace PETScWrappers
                     const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -740,7 +740,7 @@ namespace PETScWrappers
 
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -755,7 +755,7 @@ namespace PETScWrappers
     AdditionalData additional_data;
 
     /**
-     * Initializes the preconditioner object without knowing a particular
+     * Initialize the preconditioner object without knowing a particular
      * matrix. This function sets up appropriate parameters to the underlying
      * PETSc object after it has been created.
      */
@@ -873,7 +873,7 @@ namespace PETScWrappers
                            const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments.
@@ -921,7 +921,7 @@ namespace PETScWrappers
                       const AdditionalData &additional_data = AdditionalData());
 
     /**
-     * Initializes the preconditioner object and calculate all data that is
+     * Initialize the preconditioner object and calculate all data that is
      * necessary for applying it in a solver. This function is automatically
      * called when calling the constructor with the same arguments and is only
      * used if you create the preconditioner without arguments. The matrix is
diff --git a/include/deal.II/multigrid/mg_transfer_internal.h b/include/deal.II/multigrid/mg_transfer_internal.h
index 7eea670cdc..5cec19c670 100644
--- a/include/deal.II/multigrid/mg_transfer_internal.h
+++ b/include/deal.II/multigrid/mg_transfer_internal.h
@@ -59,40 +59,39 @@ namespace internal
                                   const unsigned int fe_degree);
 
     /**
-     * Stores data related to the finite element contained in the
+     * A structure that stores data related to the finite element contained in the
      * DoFHandler. Used only for the initialization using
      * <tt>setup_transfer</tt>.
      */
     template <typename Number>
     struct ElementInfo
     {
-
       /**
-       * Stores the degree of the finite element. The selection of the
+       * A variable storing the degree of the finite element. The selection of the
        * computational kernel is based on this number.
        */
       unsigned int fe_degree;
 
       /**
-       * Stores whether the element is continuous and there is a joint degree of
+       * A variable storing whether the element is continuous and there is a joint degree of
        * freedom in the center of the 1D line.
        */
       bool element_is_continuous;
 
       /**
-       * Stores the number of components in the finite element.
+       * A variable storing the number of components in the finite element.
        */
       unsigned int n_components;
 
       /**
-       * Stores the number of degrees of freedom on all child cells. It is
+       * A variable storing the number of degrees of freedom on all child cells. It is
        * <tt>2<sup>dim</sup>*fe.dofs_per_cell</tt> for DG elements and somewhat
        * less for continuous elements.
        */
       unsigned int n_child_cell_dofs;
 
       /**
-       * Holds the numbering between the numbering of degrees of freedom in
+       * An array that holds the numbering between the numbering of degrees of freedom in
        * the finite element and the lexicographic numbering needed for the
        * tensor product application.
        */
@@ -107,7 +106,7 @@ namespace internal
     };
 
     /**
-     * Sets up most of the internal data structures of MGTransferMatrixFree
+     * Set up most of the internal data structures of MGTransferMatrixFree
      */
     template <int dim, typename Number>
     void setup_transfer(const dealii::DoFHandler<dim>                                       &mg_dof,
diff --git a/include/deal.II/multigrid/mg_transfer_matrix_free.h b/include/deal.II/multigrid/mg_transfer_matrix_free.h
index 50eed0c9d9..88fe784ec7 100644
--- a/include/deal.II/multigrid/mg_transfer_matrix_free.h
+++ b/include/deal.II/multigrid/mg_transfer_matrix_free.h
@@ -152,26 +152,26 @@ public:
 private:
 
   /**
-   * Stores the degree of the finite element contained in the DoFHandler
+   * A variable storing the degree of the finite element contained in the DoFHandler
    * passed to build(). The selection of the computational kernel is based on
    * this number.
    */
   unsigned int fe_degree;
 
   /**
-   * Stores whether the element is continuous and there is a joint degree of
+   * A variable storing whether the element is continuous and there is a joint degree of
    * freedom in the center of the 1D line.
    */
   bool element_is_continuous;
 
   /**
-   * Stores the number of components in the finite element contained in the
+   * A variable storing the number of components in the finite element contained in the
    * DoFHandler passed to build().
    */
   unsigned int n_components;
 
   /**
-   * Stores the number of degrees of freedom on all child cells. It is
+   * A variable storing the number of degrees of freedom on all child cells. It is
    * <tt>2<sup>dim</sup>*fe.dofs_per_cell</tt> for DG elements and somewhat
    * less for continuous elements.
    */
@@ -190,12 +190,12 @@ private:
   std::vector<std::vector<unsigned int> > level_dof_indices;
 
   /**
-   * Stores the connectivity from parent to child cell numbers for each level.
+   * A variable storing the connectivity from parent to child cell numbers for each level.
    */
   std::vector<std::vector<std::pair<unsigned int,unsigned int> > > parent_child_connect;
 
   /**
-   * Stores the number of cells owned on a given process (sets the bounds for
+   * A variable storing the number of cells owned on a given process (sets the bounds for
    * the worker loops) for each level.
    */
   std::vector<unsigned int> n_owned_level_cells;
@@ -225,14 +225,14 @@ private:
   std::vector<AlignedVector<VectorizedArray<Number> > > weights_on_refined;
 
   /**
-   * Stores the local indices of Dirichlet boundary conditions on cells for
+   * A variable storing the local indices of Dirichlet boundary conditions on cells for
    * all levels (outer index), the cells within the levels (second index), and
    * the indices on the cell (inner index).
    */
   std::vector<std::vector<std::vector<unsigned short> > > dirichlet_indices;
 
   /**
-   * Performs templated prolongation operation
+   * Perform the prolongation operation.
    */
   template <int degree>
   void do_prolongate_add(const unsigned int                           to_level,
@@ -240,7 +240,7 @@ private:
                          const LinearAlgebra::distributed::Vector<Number> &src) const;
 
   /**
-   * Performs templated restriction operation
+   * Performs the restriction operation.
    */
   template <int degree>
   void do_restrict_add(const unsigned int                           from_level,
diff --git a/include/deal.II/sundials/kinsol.h b/include/deal.II/sundials/kinsol.h
index 4a627a519c..5adc23b74d 100644
--- a/include/deal.II/sundials/kinsol.h
+++ b/include/deal.II/sundials/kinsol.h
@@ -378,7 +378,7 @@ namespace SUNDIALS
       unsigned int maximum_non_linear_iterations;
 
       /**
-       * Specifies the scalar used as a stopping tolerance on the scaled
+       * A scalar used as a stopping tolerance on the scaled
        * maximum norm of the system function $F(u)$ or $G(u)$.
        *
        * If set to zero, default values provided by KINSOL will be used.
@@ -386,7 +386,7 @@ namespace SUNDIALS
       double function_tolerance;
 
       /**
-       * Specifies the scalar used as a stopping tolerance on the minimum
+       * A scalar used as a stopping tolerance on the minimum
        * scaled step length.
        *
        * If set to zero, default values provided by KINSOL will be used.
@@ -394,7 +394,7 @@ namespace SUNDIALS
       double step_tolerance;
 
       /**
-       * Specifies whether an initial call to the preconditioner or Jacobian
+       * Whether an initial call to the preconditioner or Jacobian
        * setup function should be made or not.
        *
        * A call to this function is useful when solving a sequence of problems,
@@ -404,7 +404,7 @@ namespace SUNDIALS
       bool no_init_setup;
 
       /**
-       * Specifies the maximum number of nonlinear iterations that can be
+       * The maximum number of nonlinear iterations that can be
        * performed between calls to the setup_jacobian() function.
        *
        * If set to zero, default values provided by KINSOL will be used.
@@ -412,14 +412,14 @@ namespace SUNDIALS
       unsigned int maximum_setup_calls;
 
       /**
-       * Specifies the maximum allowable scaled length of the Newton step.
+       * The maximum allowable scaled length of the Newton step.
        *
        * If set to zero, default values provided by KINSOL will be used.
        */
       double maximum_newton_step;
 
       /**
-       * Specifies the relative error in computing $F(u)$, which is used in the
+       * The relative error in computing $F(u)$, which is used in the
        * difference quotient approximation to the Jacobian matrix when the user
        * does not supply a solve_jacobian_system_matrix() function.
        *
@@ -428,14 +428,14 @@ namespace SUNDIALS
       double dq_relative_error;
 
       /**
-       * Specifies the maximum number of beta-condition failures in the
+       * The maximum number of beta-condition failures in the
        * linesearch algorithm. Only used if
        * strategy==SolutionStrategy::linesearch.
        */
       unsigned int maximum_beta_failures;
 
       /**
-       * Specifies the size of the subspace used with Anderson acceleration
+       * The size of the subspace used with Anderson acceleration
        * in conjunction with Picard or fixed-point iteration.
        *
        * If you set this to 0, no acceleration is used.
-- 
2.39.5