From ef8ece894418988909d4f3f4bb7542206ca9fbb9 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Sun, 8 Mar 2015 22:13:33 -0500
Subject: [PATCH] Update comments.

In particular, avoid unclear use of language for end() iterators, and
avoid references to the STL that only old-timers still understand.
---
 include/deal.II/lac/sparse_matrix.h | 122 ++++++++++++----------------
 1 file changed, 50 insertions(+), 72 deletions(-)

diff --git a/include/deal.II/lac/sparse_matrix.h b/include/deal.II/lac/sparse_matrix.h
index 5c6e63b3a3..52e3c4b52f 100644
--- a/include/deal.II/lac/sparse_matrix.h
+++ b/include/deal.II/lac/sparse_matrix.h
@@ -1354,83 +1354,61 @@ public:
    */
 //@{
 
-  /**
-   * STL-like iterator with the first entry of the matrix. This is the version
-   * for constant matrices.
-   *
-   * Note the discussion in the general documentation of this class about the
-   * order in which elements are accessed.
-   */
-  const_iterator begin () const;
-
-  /**
-   * Final iterator. This is the version for constant matrices.
-   */
-  const_iterator end () const;
-
-  /**
-   * STL-like iterator with the first entry of the matrix. This is the version
-   * for non-constant matrices.
-   *
-   * Note the discussion in the general documentation of this class about the
-   * order in which elements are accessed.
-   */
-  iterator begin ();
+    /**
+     * Return an iterator pointing to the first element of the matrix.
+     *
+     * Note the discussion in the general documentation of this class about the
+     * order in which elements are accessed.
+     */
+    const_iterator begin () const;
 
-  /**
-   * Final iterator. This is the version for non-constant matrices.
-   */
-  iterator end ();
+    /**
+     * Like the function above, but for non-const matrices.
+     */
+    iterator begin ();
+    
+    /**
+     * Return an iterator pointing the element past the last one of
+     * this matrix.
+     */
+    const_iterator end () const;
 
-  /**
-   * STL-like iterator with the first entry of row <tt>r</tt>. This is the
-   * version for constant matrices.
-   *
-   * Note that if the given row is empty, i.e. does not contain any nonzero
-   * entries, then the iterator returned by this function equals
-   * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
-   * that case.
-   *
-   * Note also the discussion in the general documentation of this class about
-   * the order in which elements are accessed.
-   */
-  const_iterator begin (const size_type r) const;
+    /**
+     * Like the function above, but for non-const matrices.
+     */
+    iterator end ();
+    
+    /**
+     * Return an iterator pointing to the first element of row @p r.
+     *
+     * Note that if the given row is empty, i.e. does not contain any
+     * nonzero entries, then the iterator returned by this function
+     * equals <tt>end(r)</tt>. The returned iterator may not be
+     * dereferencable in that case if neither row @p r nor any of the
+     * following rows contain any nonzero entries.
+     */
+    const_iterator begin (const size_type r) const;
 
-  /**
-   * Final iterator of row <tt>r</tt>. It points to the first element past the
-   * end of line @p r, or past the end of the entire sparsity pattern. This is
-   * the version for constant matrices.
-   *
-   * Note that the end iterator is not necessarily dereferencable. This is in
-   * particular the case if it is the end iterator for the last row of a
-   * matrix.
-   */
-  const_iterator end (const size_type r) const;
+    /**
+     * Like the function above, but for non-const matrices.
+     */
+    iterator begin (const size_type r);
 
-  /**
-   * STL-like iterator with the first entry of row <tt>r</tt>. This is the
-   * version for non-constant matrices.
-   *
-   * Note that if the given row is empty, i.e. does not contain any nonzero
-   * entries, then the iterator returned by this function equals
-   * <tt>end(r)</tt>. Note also that the iterator may not be dereferencable in
-   * that case.
-   *
-   * Note the discussion in the general documentation of this class about the
-   * order in which elements are accessed.
-   */
-  iterator begin (const size_type r);
+    /**
+     * Return an iterator pointing the element past the last one of
+     * row @p r , or past the end of the entire sparsity pattern if
+     * none of the rows after @p r contain any entries at all.
+     *
+     * Note that the end iterator is not necessarily dereferencable. This is
+     * in particular the case if it is the end iterator for the last row of a
+     * matrix.
+     */
+    const_iterator end (const size_type r) const;
 
-  /**
-   * Final iterator of row <tt>r</tt>. It points to the first element past the
-   * end of line @p r, or past the end of the entire sparsity pattern. This is
-   * the version for non-constant matrices.
-   *
-   * Note that the end iterator is not necessarily dereferencable. This is in
-   * particular the case if it is the end iterator for the last row of a
-   * matrix.
-   */
-  iterator end (const size_type r);
+    /**
+     * Like the function above, but for non-const matrices.
+     */
+    iterator end (const size_type r);
 //@}
   /**
    * @name Input/Output
-- 
2.39.5