[mlir][sparse] Address style nit in documentation

[wrengr]

rebase

[wrengr]

reuploading

mlir/include/mlir/ExecutionEngine/SparseTensor/COO.h

struct Element final {
   V value;
 };
 
 /// Closure object for `operator<` on `Element` with a given rank.
 template <typename V>
 struct ElementLT final {
   ElementLT(uint64_t rank) : rank(rank) {}
 
-  /// Compare two elements a la `operator<`.
+  /// Compares two elements a la `operator<`.
   ///
   /// Precondition: the elements must both be valid for `rank`.
   bool operator()(const Element<V> &e1, const Element<V> &e2) const {
     for (uint64_t d = 0; d < rank; ++d) {
       if (e1.indices[d] == e2.indices[d])
         continue;
       return e1.indices[d] < e2.indices[d];
     }
static SparseTensorCOO<V> *newSparseTensorCOO(uint64_t rank,
     std::vector<uint64_t> permsz(rank);
     for (uint64_t r = 0; r < rank; ++r) {
       assert(dimSizes[r] > 0 && "Dimension size zero has trivial storage");
       permsz[perm[r]] = dimSizes[r];
     }
     return new SparseTensorCOO<V>(permsz, capacity);
   }
 
-  /// Get the rank of the tensor.
+  /// Gets the rank of the tensor.
   uint64_t getRank() const { return dimSizes.size(); }
 
-  /// Get the dimension-sizes array.
+  /// Gets the dimension-sizes array.
   const std::vector<uint64_t> &getDimSizes() const { return dimSizes; }
 
-  /// Get the elements array.
+  /// Gets the elements array.
   const std::vector<Element<V>> &getElements() const { return elements; }
 
   /// Returns the `operator<` closure object for the COO's element type.
   ElementLT<V> getElementLT() const { return ElementLT<V>(getRank()); }
 
   /// Adds an element to the tensor.  This method does not check whether
   /// `ind` is already associated with a value, it adds it regardless.
   /// Resolving such conflicts is left up to clients of the iterator
public:
   void sort() {
     assert(!iteratorLocked && "Attempt to sort() after startIterator()");
     if (isSorted)
       return;
     std::sort(elements.begin(), elements.end(), getElementLT());
     isSorted = true;
   }
 
-  /// Switch into iterator mode.  If already in iterator mode, then
+  /// Switches into iterator mode.  If already in iterator mode, then
   /// resets the position to the first element.
   void startIterator() {
     iteratorLocked = true;
     iteratorPos = 0;
   }
 
-  /// Get the next element.  If there are no remaining elements, then
+  /// Gets the next element.  If there are no remaining elements, then
   /// returns nullptr and switches out of iterator mode.
   ///
   /// Asserts: is in iterator mode.
   const Element<V> *getNext() {
     assert(iteratorLocked && "Attempt to getNext() before startIterator()");
     if (iteratorPos < elements.size())
       return &(elements[iteratorPos++]);
     iteratorLocked = false;

mlir/include/mlir/ExecutionEngine/SparseTensor/File.h

uint64_t getDimSize(uint64_t d) const {
     return idata[2 + d];
   }
 
   /// Asserts the shape subsumes the actual dimension sizes.  Is only
   /// valid after parsing the header.
   void assertMatchesShape(uint64_t rank, const uint64_t *shape) const;
 
 private:
-  /// Read the MME header of a general sparse matrix of type real.
+  /// Reads the MME header of a general sparse matrix of type real.
   void readMMEHeader();
 
-  /// Read the "extended" FROSTT header. Although not part of the
+  /// Reads the "extended" FROSTT header. Although not part of the
   /// documented format, we assume that the file starts with optional
   /// comments followed by two lines that define the rank, the number of
   /// nonzeros, and the dimensions sizes (one per rank) of the sparse tensor.
   void readExtFROSTTHeader();
 
   static constexpr int kColWidth = 1025;
   const char *const filename;
   FILE *file = nullptr;

mlir/include/mlir/ExecutionEngine/SparseTensor/Storage.h

public:
   /// The `dimSizes` and `sparsity` arrays are already in storage-order.
   ///
   /// Precondition: `perm` and `sparsity` must be valid for `dimSizes.size()`.
   SparseTensorStorageBase(const std::vector<uint64_t> &dimSizes,
                           const uint64_t *perm, const DimLevelType *sparsity);
 
   virtual ~SparseTensorStorageBase() = default;
 
-  /// Get the rank of the tensor.
+  /// Gets the rank of the tensor.
   uint64_t getRank() const { return dimSizes.size(); }
 
-  /// Get the dimension-sizes array, in storage-order.
+  /// Gets the dimension-sizes array, in storage-order.
   const std::vector<uint64_t> &getDimSizes() const { return dimSizes; }
 
-  /// Safely lookup the size of the given (storage-order) dimension.
+  /// Safely looks up the size of the given (storage-order) dimension.
   uint64_t getDimSize(uint64_t d) const {
     ASSERT_VALID_DIM(d);
     return dimSizes[d];
   }
 
-  /// Get the "reverse" permutation, which maps this object's
+  /// Gets the "reverse" permutation, which maps this object's
   /// storage-order to the tensor's semantic-order.
   const std::vector<uint64_t> &getRev() const { return rev; }
 
-  /// Get the dimension-types array, in storage-order.
+  /// Gets the dimension-types array, in storage-order.
   const std::vector<DimLevelType> &getDimTypes() const { return dimTypes; }
 
-  /// Safely lookup the level-type of the given (storage-order) dimension.
+  /// Safely looks up the level-type of the given (storage-order) dimension.
   DimLevelType getDimType(uint64_t d) const {
     ASSERT_VALID_DIM(d);
     return dimTypes[d];
   }
 
-  /// Safely check if the (storage-order) dimension uses dense storage.
+  /// Safely checks if the (storage-order) dimension uses dense storage.
   bool isDenseDim(uint64_t d) const { return isDenseDLT(getDimType(d)); }
 
-  /// Safely check if the (storage-order) dimension uses compressed storage.
+  /// Safely checks if the (storage-order) dimension uses compressed storage.
   bool isCompressedDim(uint64_t d) const {
     return isCompressedDLT(getDimType(d));
   }
 
-  /// Safely check if the (storage-order) dimension uses singleton storage.
+  /// Safely checks if the (storage-order) dimension uses singleton storage.
   bool isSingletonDim(uint64_t d) const {
     return isSingletonDLT(getDimType(d));
   }
 
-  /// Safely check if the (storage-order) dimension is ordered.
+  /// Safely checks if the (storage-order) dimension is ordered.
   bool isOrderedDim(uint64_t d) const { return isOrderedDLT(getDimType(d)); }
 
-  /// Safely check if the (storage-order) dimension is unique.
+  /// Safely checks if the (storage-order) dimension is unique.
   bool isUniqueDim(uint64_t d) const { return isUniqueDLT(getDimType(d)); }
 
-  /// Allocate a new enumerator.
+  /// Allocates a new enumerator.
 #define DECL_NEWENUMERATOR(VNAME, V)                                           \
   virtual void newEnumerator(SparseTensorEnumeratorBase<V> **, uint64_t,       \
                              const uint64_t *) const;
   MLIR_SPARSETENSOR_FOREVERY_V(DECL_NEWENUMERATOR)
 #undef DECL_NEWENUMERATOR
 
-  /// Pointers-overhead storage.
+  /// Gets pointers-overhead storage.
 #define DECL_GETPOINTERS(PNAME, P)                                             \
   virtual void getPointers(std::vector<P> **, uint64_t);
   MLIR_SPARSETENSOR_FOREVERY_FIXED_O(DECL_GETPOINTERS)
 #undef DECL_GETPOINTERS
 
-  /// Indices-overhead storage.
+  /// Gets indices-overhead storage.
 #define DECL_GETINDICES(INAME, I)                                              \
   virtual void getIndices(std::vector<I> **, uint64_t);
   MLIR_SPARSETENSOR_FOREVERY_FIXED_O(DECL_GETINDICES)
 #undef DECL_GETINDICES
 
-  /// Primary storage.
+  /// Gets primary storage.
 #define DECL_GETVALUES(VNAME, V) virtual void getValues(std::vector<V> **);
   MLIR_SPARSETENSOR_FOREVERY_V(DECL_GETVALUES)
 #undef DECL_GETVALUES
 
   /// Element-wise insertion in lexicographic index order.
 #define DECL_LEXINSERT(VNAME, V) virtual void lexInsert(const uint64_t *, V);
   MLIR_SPARSETENSOR_FOREVERY_V(DECL_LEXINSERT)
 #undef DECL_LEXINSERT
public:
   /// Finalizes lexicographic insertions.
   void endInsert() final {
     if (values.empty())
       finalizeSegment(0);
     else
       endPath(0);
   }
 
-  /// Allocate a new enumerator for this classes `<P,I,V>` types and
+  /// Allocates a new enumerator for this classes `<P,I,V>` types and
   /// erase the `<P,I>` parts from the type.  Callers must make sure to
   /// delete the enumerator when they're done with it.
   void newEnumerator(SparseTensorEnumeratorBase<V> **out, uint64_t rank,
                      const uint64_t *perm) const final {
     *out = new SparseTensorEnumerator<P, I, V>(*this, rank, perm);
   }
 
   /// Returns this sparse tensor storage scheme as a new memory-resident
while (lo < hi) { // If `hi` is unchanged, then `lo < elements.size()`.
       fromCOO(elements, lo, seg, d + 1);
       // And move on to next segment in interval.
       lo = seg;
     }
     // Finalize the sparse pointer structure at this dimension.
     finalizeSegment(d, full);
   }
 
-  /// Finalize the sparse pointer structure at this dimension.
+  /// Finalizes the sparse pointer structure at this dimension.
   void finalizeSegment(uint64_t d, uint64_t full = 0, uint64_t count = 1) {
     if (count == 0)
       return; // Short-circuit, since it'll be a nop.
     if (isCompressedDim(d)) {
       appendPointer(d, indices[d].size(), count);
     } else if (isSingletonDim(d)) {
       return;
     } else { // Dense dimension.

 /// a source tensor, for direct sparse=>sparse conversion a la
 /// <https://arxiv.org/abs/2001.02609>.
 ///
 /// N.B., this class stores references to the parameters passed to
 /// the constructor; thus, objects of this class must not outlive
 /// those parameters.
 class SparseTensorNNZ final {
 public:
-  /// Allocate the statistics structure for the desired sizes and
+  /// Allocates the statistics structure for the desired sizes and
   /// sparsity (in the target tensor's storage-order).  This constructor
   /// does not actually populate the statistics, however; for that see
   /// `initialize`.
   ///
   /// Precondition: `dimSizes` must not contain zeros.
   SparseTensorNNZ(const std::vector<uint64_t> &dimSizes,
                   const std::vector<DimLevelType> &sparsity);
 
   // We disallow copying to help avoid leaking the stored references.
   SparseTensorNNZ(const SparseTensorNNZ &) = delete;
   SparseTensorNNZ &operator=(const SparseTensorNNZ &) = delete;
 
   /// Returns the rank of the target tensor.
   uint64_t getRank() const { return dimSizes.size(); }
 
-  /// Enumerate the source tensor to fill in the statistics.  The
+  /// Enumerates the source tensor to fill in the statistics.  The
   /// enumerator should already incorporate the permutation (from
   /// semantic-order to the target storage-order).
   template <typename V>
   void initialize(SparseTensorEnumeratorBase<V> &enumerator) {
     assert(enumerator.getRank() == getRank() && "Tensor rank mismatch");
     assert(enumerator.permutedSizes() == dimSizes && "Tensor size mismatch");
     enumerator.forallElements(
         [this](const std::vector<uint64_t> &ind, V) { add(ind); });