From 77e652d8ad3eea056e24e7458ad2ba17688723d5 Mon Sep 17 00:00:00 2001
From: Gael Guennebaud <g.gael@free.fr>
Date: Wed, 1 Jun 2016 10:03:32 +0200
Subject: Doc: improve documentation of Map<SparseMatrix>

---
 Eigen/src/SparseCore/SparseMap.h | 20 ++++++++++++++++----
 doc/SparseQuickReference.dox     | 16 +++++++++++++++-
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/Eigen/src/SparseCore/SparseMap.h b/Eigen/src/SparseCore/SparseMap.h
index eb241c3e2..d76f3b68f 100644
--- a/Eigen/src/SparseCore/SparseMap.h
+++ b/Eigen/src/SparseCore/SparseMap.h
@@ -166,12 +166,17 @@ class SparseMapBase<Derived,WriteAccessors>
     using Base::innerIndexPtr;
     using Base::outerIndexPtr;
     using Base::innerNonZeroPtr;
-    inline Scalar* valuePtr()       { return Base::m_values; }
+    /** \copydoc SparseMatrix::valuePtr */
+    inline Scalar* valuePtr()              { return Base::m_values; }
+    /** \copydoc SparseMatrix::innerIndexPtr */
     inline StorageIndex* innerIndexPtr()   { return Base::m_innerIndices; }
+    /** \copydoc SparseMatrix::outerIndexPtr */
     inline StorageIndex* outerIndexPtr()   { return Base::m_outerIndex; }
+    /** \copydoc SparseMatrix::innerNonZeroPtr */
     inline StorageIndex* innerNonZeroPtr() { return Base::m_innerNonZeros; }
     //----------------------------------------
 
+    /** \copydoc SparseMatrix::coeffRef */
     inline Scalar& coeffRef(Index row, Index col)
     {
       const Index outer = IsRowMajor ? row : col;
@@ -188,7 +193,7 @@ class SparseMapBase<Derived,WriteAccessors>
     }
     
     inline SparseMapBase(Index rows, Index cols, Index nnz, StorageIndex* outerIndexPtr, StorageIndex* innerIndexPtr,
-                              Scalar* valuePtr, StorageIndex* innerNonZerosPtr = 0)
+                         Scalar* valuePtr, StorageIndex* innerNonZerosPtr = 0)
       : Base(rows, cols, nnz, outerIndexPtr, innerIndexPtr, valuePtr, innerNonZerosPtr)
     {}
 
@@ -233,13 +238,15 @@ class Map<SparseMatrixType>
       * stored as a sparse format as defined by the pointers \a outerIndexPtr, \a innerIndexPtr, and \a valuePtr.
       * If the optional parameter \a innerNonZerosPtr is the null pointer, then a standard compressed format is assumed.
       *
+      * This constructor is available only if \c SparseMatrixType is non-const.
+      *
       * More details on the expected storage schemes are given in the \ref TutorialSparse "manual pages".
       */
     inline Map(Index rows, Index cols, Index nnz, StorageIndex* outerIndexPtr,
                StorageIndex* innerIndexPtr, Scalar* valuePtr, StorageIndex* innerNonZerosPtr = 0)
       : Base(rows, cols, nnz, outerIndexPtr, innerIndexPtr, valuePtr, innerNonZerosPtr)
     {}
-
+#ifndef EIGEN_PARSED_BY_DOXYGEN
     /** Empty destructor */
     inline ~Map() {}
 };
@@ -254,7 +261,12 @@ class Map<const SparseMatrix<MatScalar,MatOptions,MatIndex>, Options, StrideType
     enum { IsRowMajor = Base::IsRowMajor };
 
   public:
-
+#endif
+    /** This is the const version of the above constructor.
+      *
+      * This constructor is available only if \c SparseMatrixType is const, e.g.:
+      * \code Map<const SparseMatrix<double> >  \endcode
+      */
     inline Map(Index rows, Index cols, Index nnz, const StorageIndex* outerIndexPtr,
                const StorageIndex* innerIndexPtr, const Scalar* valuePtr, const StorageIndex* innerNonZerosPtr = 0)
       : Base(rows, cols, nnz, outerIndexPtr, innerIndexPtr, valuePtr, innerNonZerosPtr)
diff --git a/doc/SparseQuickReference.dox b/doc/SparseQuickReference.dox
index e0a30edcc..a25622e80 100644
--- a/doc/SparseQuickReference.dox
+++ b/doc/SparseQuickReference.dox
@@ -206,7 +206,7 @@ See \ref TutorialSparse_SubMatrices and below for read-write sub-matrices.
   sm1.innerVectors(start, size);    // RW
   sm1.leftCols(size);               // RW
   sm2.rightCols(size);              // RO because sm2 is row-major
-  sm1.middleRows(start, numRows);   // RO becasue sm1 is column-major
+  sm1.middleRows(start, numRows);   // RO because sm1 is column-major
   sm1.middleCols(start, numCols);   // RW
   sm1.col(j);                       // RW
 \endcode
@@ -253,6 +253,20 @@ If the matrix is not in compressed form, makeCompressed() should be called befor
 Note that these functions are mostly provided for interoperability purposes with external libraries.\n
 A better access to the values of the matrix is done by using the InnerIterator class as described in \link TutorialSparse the Tutorial Sparse \endlink section</td>
 </tr>
+<tr class="alt"><td colspan="2">Mapping external buffers</td></tr>
+<tr class="alt">
+<td>
+\code
+int outerIndexPtr[cols+1];
+int innerIndices[nnz];
+double values[nnz];
+Map<SparseMatrix<double> > sm1(rows,cols,nnz,outerIndexPtr, // read-write
+                               innerIndices,values);
+Map<const SparseMatrix<double> > sm2(...);                  // read-only
+\endcode
+</td>
+<td>As for dense matrices, class Map<SparseMatrixType> can be used to see external buffers as an %Eigen's SparseMatrix object. </td>
+</tr>
 </table>
 */
 }
-- 
cgit v1.2.3