Clean up informal language, vague TODOs, and dead code in comments

libeigen/eigen!2191

Co-authored-by: Rasmus Munk Larsen <rmlarsen@gmail.com>

Eigen/src/SparseCore/ConservativeSparseSparseProduct.h

@@ -79,8 +79,8 @@ static void conservative_sparse_sparse_product_impl(const Lhs& lhs, const Rhs& r
       const Index t200 = rows / 11;  // 11 == (log2(200)*1.39)
       const Index t = (rows * 100) / 139;
 
-      // FIXME reserve nnz non zeros
-      // FIXME implement faster sorting algorithms for very small nnz
+      // FIXME: reserve space for the expected number of non-zeros.
+      // FIXME: implement faster sorting for very small nnz counts.
       // if the result is sparse enough => use a quick sort
       // otherwise => loop through the entire vector
       // In order to avoid to perform an expensive log2 when the
@@ -131,7 +131,7 @@ struct conservative_sparse_sparse_product_selector<Lhs, Rhs, ResultType, ColMajo
 
     // If the result is tall and thin (in the extreme case a column vector)
     // then it is faster to sort the coefficients inplace instead of transposing twice.
-    // FIXME, the following heuristic is probably not very good.
+    // FIXME: this heuristic has known limitations and should be improved.
     if (lhs.rows() > rhs.cols()) {
       using ColMajorMatrix = typename sparse_eval<ColMajorMatrixAux, ResultType::RowsAtCompileTime,
                                                   ResultType::ColsAtCompileTime, ColMajorMatrixAux::Flags>::type;

Eigen/src/SparseCore/SparseDiagonalProduct.h

@@ -39,7 +39,11 @@ struct product_evaluator<Product<Lhs, Rhs, DefaultProduct>, ProductTag, Diagonal
     : public sparse_diagonal_product_evaluator<Rhs, typename Lhs::DiagonalVectorType,
                                                Rhs::Flags & RowMajorBit ? SDP_AsScalarProduct : SDP_AsCwiseProduct> {
   typedef Product<Lhs, Rhs, DefaultProduct> XprType;
-  enum { CoeffReadCost = HugeCost, Flags = Rhs::Flags & RowMajorBit, Alignment = 0 };  // FIXME CoeffReadCost & Flags
+  enum {
+    CoeffReadCost = HugeCost,
+    Flags = Rhs::Flags & RowMajorBit,
+    Alignment = 0
+  };  // FIXME: compute proper CoeffReadCost and propagate Flags.
 
   typedef sparse_diagonal_product_evaluator<Rhs, typename Lhs::DiagonalVectorType,
                                             Rhs::Flags & RowMajorBit ? SDP_AsScalarProduct : SDP_AsCwiseProduct>
@@ -52,7 +56,11 @@ struct product_evaluator<Product<Lhs, Rhs, DefaultProduct>, ProductTag, SparseSh
     : public sparse_diagonal_product_evaluator<Lhs, Transpose<const typename Rhs::DiagonalVectorType>,
                                                Lhs::Flags & RowMajorBit ? SDP_AsCwiseProduct : SDP_AsScalarProduct> {
   typedef Product<Lhs, Rhs, DefaultProduct> XprType;
-  enum { CoeffReadCost = HugeCost, Flags = Lhs::Flags & RowMajorBit, Alignment = 0 };  // FIXME CoeffReadCost & Flags
+  enum {
+    CoeffReadCost = HugeCost,
+    Flags = Lhs::Flags & RowMajorBit,
+    Alignment = 0
+  };  // FIXME: compute proper CoeffReadCost and propagate Flags.
 
   typedef sparse_diagonal_product_evaluator<Lhs, Transpose<const typename Rhs::DiagonalVectorType>,
                                             Lhs::Flags & RowMajorBit ? SDP_AsCwiseProduct : SDP_AsScalarProduct>

Eigen/src/SparseCore/SparseMatrix.h

@@ -1548,7 +1548,7 @@ SparseMatrix<Scalar, Options_, StorageIndex_>::operator=(const SparseMatrixBase<
     Eigen::Map<IndexVector>(dest.m_outerIndex, dest.outerSize()).setZero();
 
     // pass 1
-    // FIXME the above copy could be merged with that pass
+    // FIXME: merge the above copy into this pass to avoid iterating twice.
     for (Index j = 0; j < otherCopy.outerSize(); ++j)
       for (typename OtherCopyEval::InnerIterator it(otherCopyEval, j); it; ++it) ++dest.m_outerIndex[it.index()];
 

Eigen/src/SparseCore/SparseMatrixBase.h

@@ -115,7 +115,7 @@ class SparseMatrixBase : public EigenBase<Derived> {
   typedef Transpose<Derived> TransposeReturnType;
   typedef Transpose<const Derived> ConstTransposeReturnType;
 
-  // FIXME storage order do not match evaluator storage order
+  // FIXME: storage order may not match evaluator storage order.
   typedef SparseMatrix<Scalar, Flags & RowMajorBit ? RowMajor : ColMajor, StorageIndex> PlainObject;
 
   /** This is the "real scalar" type; if the \a Scalar type is already real numbers
@@ -203,7 +203,7 @@ class SparseMatrixBase : public EigenBase<Derived> {
     return derived();
   }
 
-  SparseMatrixBase() : m_isRValue(false) { /* TODO check flags */
+  SparseMatrixBase() : m_isRValue(false) { /* TODO: validate traits flags. */
   }
 
   template <typename OtherDerived>

Eigen/src/SparseCore/SparseRef.h

@@ -117,7 +117,8 @@ class Ref<SparseMatrix<MatScalar, MatOptions, MatIndex>, Options, StrideType>
 #else
 template <typename SparseMatrixType, int Options>
 class Ref<SparseMatrixType, Options>
-    : public SparseMapBase<Derived, WriteAccessors>  // yes, that's weird to use Derived here, but that works!
+    : public SparseMapBase<Derived, WriteAccessors>  // Note: 'Derived' is used here intentionally; it resolves
+                                                     // correctly via CRTP.
 #endif
 {
   typedef SparseMatrix<MatScalar, MatOptions, MatIndex> PlainObjectType;

Eigen/src/SparseCore/SparseSparseProductWithPruning.h

@@ -56,14 +56,11 @@ static void sparse_sparse_product_with_pruning_impl(const Lhs& lhs, const Rhs& r
   res.reserve(estimated_nnz_prod);
   double ratioColRes = double(estimated_nnz_prod) / (double(lhs.rows()) * double(rhs.cols()));
   for (Index j = 0; j < cols; ++j) {
-    // FIXME:
-    // double ratioColRes = (double(rhs.innerVector(j).nonZeros()) +
-    // double(lhs.nonZeros())/double(lhs.cols()))/double(lhs.rows());
-    // let's do a more accurate determination of the nnz ratio for the current column j of res
+    // FIXME: compute a more accurate per-column nnz ratio for res.
     tempVector.init(ratioColRes);
     tempVector.setZero();
     for (typename evaluator<Rhs>::InnerIterator rhsIt(rhsEval, j); rhsIt; ++rhsIt) {
-      // FIXME should be written like this: tmp += rhsIt.value() * lhs.col(rhsIt.index())
+      // FIXME: rewrite as tmp += rhsIt.value() * lhs.col(rhsIt.index()).
       tempVector.restart();
       RhsScalar x = rhsIt.value();
       for (typename evaluator<Lhs>::InnerIterator lhsIt(lhsEval, rhsIt.index()); lhsIt; ++lhsIt) {

Eigen/src/SparseCore/SparseUtil.h

@@ -105,7 +105,7 @@ struct sparse_eval<T, Rows, 1, Flags> {
   typedef SparseVector<Scalar_, ColMajor, StorageIndex_> type;
 };
 
-// TODO this seems almost identical to plain_matrix_type<T, Sparse>
+// TODO: consider unifying with plain_matrix_type<T, Sparse>.
 template <typename T, int Rows, int Cols, int Flags>
 struct sparse_eval {
   typedef typename traits<T>::Scalar Scalar_;

Eigen/src/SparseCore/TriangularSolver.h

@@ -195,7 +195,7 @@ struct sparse_solve_triangular_sparse_selector<Lhs, Rhs, Mode, UpLo, ColMajor> {
     res.reserve(other.nonZeros());
 
     for (Index col = 0; col < other.cols(); ++col) {
-      // FIXME estimate number of non zeros
+      // FIXME: estimate the number of non-zeros per column for better allocation.
       tempVector.init(.99 /*float(other.col(col).nonZeros())/float(other.rows())*/);
       tempVector.setZero();
       tempVector.restart();
@@ -230,16 +230,11 @@ struct sparse_solve_triangular_sparse_selector<Lhs, Rhs, Mode, UpLo, ColMajor> {
         }
       }
 
-      //       Index count = 0;
-      // FIXME compute a reference value to filter zeros
+      // FIXME: compute a reference value to filter zeros.
       for (typename AmbiVector<Scalar, StorageIndex>::Iterator it(tempVector /*,1e-12*/); it; ++it) {
-        //         ++ count;
-        //         std::cerr << "fill " << it.index() << ", " << col << "\n";
-        //         std::cout << it.value() << "  ";
-        // FIXME use insertBack
+        // FIXME: use insertBack for better performance.
         res.insert(it.index(), col) = it.value();
       }
-      //       std::cout << "tempVector.nonZeros() == " << int(count) << " / " << (other.rows()) << "\n";
     }
     res.finalize();
     other = res.markAsRValue();