eina: Cleanup documentation for Sparse Matrix.

Summary:
Revises some descriptions, polishes wording, makes punctuation and
formatting more consistent, and straightens out some convoluted grammar
here and there.

There are a few places where the parameter documentation was incorrectly
cut-and-pasted from other routines, so this is fixed.  Also, in
eina_matrixsparse_iterator_new() the docs say the elements are not
returned sequentially, but from the context and code I think it meant to
say they're not _consecutive_.

Subscribers: cedric

Differential Revision: https://phab.enlightenment.org/D5924

Reviewed-by: Cedric BAIL <cedric@osg.samsung.com>

1 files changed, 100 insertions, 92 deletions

diff --git a/src/lib/eina/eina_matrixsparse.h b/src/lib/eina/eina_matrixsparse.h
index 301b7785e2..e6988c5ab2 100644
--- a/src/lib/eina/eina_matrixsparse.h
+++ b/src/lib/eina/eina_matrixsparse.h
@@ -30,7 +30,13 @@
 /**
  * @addtogroup Eina_Matrixsparse_Group Sparse Matrix
  *
- * @brief These functions provide matrix sparse management.
+ * @brief These functions manage sparse matrices.
+ *
+ * A sparse matrix stores data objects in cells within a row / column
+ * tabular structure, where the majority of cells will be empty.  The
+ * sparse matrix takes advantage of this emptiness by allocating memory
+ * only for non-empty cells and, in this implementation, storing them
+ * internally in linked lists.
  *
  * For more information, you can look at the @ref tutorial_matrixsparse_page.
  */
@@ -96,25 +102,25 @@ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
                                               const void *user_data);
 
 /**
- * @brief Frees resources allocated for Sparse Matrix.
+ * @brief Frees resources allocated for a Sparse Matrix.
  *
- * @param[in] m The Sparse Matrix instance to free, must @b not be @c NULL.
+ * @param[in] m The Sparse Matrix instance to free; must @b not be @c NULL.
  */
 EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m);
 
 /* size manipulation */
 
 /**
- * @brief Gets the current size of Sparse Matrix.
+ * @brief Gets the current size of a Sparse Matrix.
  *
  * The given parameters are guaranteed to be set if they're not @c NULL,
- * even if this function fails (ie: @a m is not a valid matrix instance).
+ * even if this function fails (i.e.: @a m is not a valid matrix instance).
  *
  * @param[in] m The sparse matrix to operate on.
- * @param[out] rows Returns the number of rows, may be @c NULL. If @a m
+ * @param[out] rows Returns the number of rows; may be @c NULL. If @a m
  *        is invalid, returned value is zero, otherwise it's a positive
  *        integer.
- * @param[out] cols Returns the number of columns, may be @c NULL. If @a m is
+ * @param[out] cols Returns the number of columns; may be @c NULL. If @a m is
  *        invalid, returned value is zero, otherwise it's a positive integer.
  */
 EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
@@ -124,28 +130,27 @@ EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
 /**
  * @brief Resizes the Sparse Matrix.
  *
- * This will resize the sparse matrix, possibly freeing cells on rows
- * and columns that will cease to exist.
+ * This will resize the sparse matrix, potentially freeing cells on rows
+ * and columns that will no longer exist.
  *
- * @param[out] m The sparse matrix to operate on.
- * @param[in] rows The new number of rows, must be greater than zero.
- * @param[in] cols The new number of columns, must be greater than zero.
+ * @param[in,out] m The sparse matrix to operate on.
+ * @param[in] rows The new number of rows; must be greater than zero.
+ * @param[in] cols The new number of columns; must be greater than zero.
  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
  *
  * @warning Cells, rows or columns are not reference counted and thus
- *     after this call any reference might be invalid if instance were
- *     freed.
+ *     references to freed instances may become invalid.
  */
 EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
                                           unsigned long      rows,
                                           unsigned long      cols);
 
-/* data getting */
+/* Data getting */
 
 /**
- * @brief Gets the cell reference inside Sparse Matrix.
+ * @brief Gets the cell reference inside the Sparse Matrix.
  *
- * @param[in] m The sparse matrix to operate on.
+ * @param[in] m The sparse matrix.
  * @param[in] row The new number of row to clear.
  * @param[in] col The new number of column to clear.
  * @param[out] cell Pointer to return cell reference, if any exists.
@@ -174,8 +179,8 @@ EAPI void     *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel
  * @brief Gets data associated with given cell given its indexes.
  *
  * @param[in] m The sparse matrix to operate on.
- * @param[in] row The new number of row to clear.
- * @param[in] col The new number of column to clear.
+ * @param[in] row The row number.
+ * @param[in] col The column number.
  *
  * @return Data associated with given cell or @c NULL if nothing is associated.
  *
@@ -185,22 +190,23 @@ EAPI void     *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel
 EAPI void     *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col);
 
 /**
- * @brief Gets position (indexes) of the given cell.
+ * @brief Gets the row and column position of the given cell.
  *
- * @param[in] cell The cell reference, must @b not be @c NULL.
- * @param[out] row Where to store cell row number, may be @c NULL.
- * @param[out] col Where to store cell column number, may be @c NULL.
+ * @param[in] cell The cell reference; must @b not be @c NULL.
+ * @param[out] row The returned row number; may be @c NULL.
+ * @param[out] col The returned column number; may be @c NULL.
  *
  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL).
  */
 EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col);
 
-/* data setting */
+
+/* Data setting */
 
 /**
  * @brief Changes cell reference value without freeing the possibly existing old value.
  *
- * @param[in,out] cell The cell reference, must @b not be @c NULL.
+ * @param[in,out] cell The cell reference; must @b not be @c NULL.
  * @param[in] data New data to set.
  * @param[out] p_old Returns the old value intact (not freed).
  *
@@ -212,14 +218,14 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell
 EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, const void *data, void **p_old);
 
 /**
- * @brief Changes cell value freeing the possibly existing old value.
+ * @brief Changes cell value, freeing any previously existing value.
  *
- * In contrast to eina_matrixsparse_cell_data_replace(), this function will
- * call @c free_func() on existing value.
- *
- * @param[in,out] cell The cell reference, must @b not be @c NULL.
+ * @param[in,out] cell The cell reference; must @b not be @c NULL.
  * @param[in] data New data to set.
  *
+ * In contrast to eina_matrixsparse_cell_data_replace(), this function will
+ * call @c free_func() on the existing value, if one exists.
+ *
  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
  *
  * @see eina_matrixsparse_cell_data_replace()
@@ -228,16 +234,17 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell,
 EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data);
 
 /**
- * @brief Changes cell value without freeing the possibly existing old value, using
- * indexes.
+ * @brief Changes cell value at a given row and column position, without
+ * freeing previously existing values.
  *
- * @param[in,out] m The sparse matrix, must @b not be @c NULL.
- * @param[in] row The row number to set the value.
- * @param[in] col The column number to set the value.
+ * @param[in,out] m The sparse matrix; must @b not be @c NULL.
+ * @param[in] row The row number.
+ * @param[in] col The column number.
  * @param[in] data New data to set.
- * @param[out] p_old returns the old value intact (not freed).
+ * @param[out] p_old The previous value, returned intact (not freed).
  *
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL,
+ * or row, column indexes are not valid).
  *
  * @see eina_matrixsparse_cell_data_replace()
  * @see eina_matrixsparse_data_idx_set()
@@ -245,17 +252,17 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, con
 EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old);
 
 /**
- * @brief Changes cell value freeing the possibly existing old value, using
- * indexes.
- *
- * In contrast to eina_matrixsparse_data_idx_replace(), this function will
- * call @c free_func() on existing value.
+ * @brief Changes cell value at a given row and column position, freeing
+ * any previously existing value.
  *
  * @param[in,out] m The sparse matrix, must @b not be @c NULL.
  * @param[in] row The row number to set the value.
  * @param[in] col The column number to set the value.
  * @param[in] data New data to set.
  *
+ * In contrast to eina_matrixsparse_data_idx_replace(), this function will
+ * call @c free_func() on the existing value, if one exists.
+ *
  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
  *
  * @see eina_matrixsparse_cell_data_replace()
@@ -265,21 +272,20 @@ EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned lon
 /* data deleting */
 
 /**
- * @brief Clears (erases all cells) of row given its index.
+ * @brief Clears (erases all cells) of a given row number.
+ *
+ * @param[in,out] m The sparse matrix to operate on.
+ * @param[in] row The row number to clear.
  *
  * Existing cells will be cleared with @c free_func() given to
  * eina_matrixsparse_new().
  *
- * @param[in,out] m The sparse matrix to operate on.
- * @param[in] row The new number of row to clear.
- *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered successful if row
- *     had no cells filled. Failure is asking for clear row outside
- *     matrix size.
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure (such as
+ *     requesting a row outside the matrix's defined size). It is
+ *     considered successful if the row had no cells filled.
  *
  * @warning Cells, rows or columns are not reference counted and thus
- *     after this call any reference might be invalid if instance were
- *     freed.
+ *     references to freed instances may become invalid.
  */
 EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row);
 
@@ -290,70 +296,70 @@ EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned lo
  * eina_matrixsparse_new().
  *
  * @param[in,out] m The sparse matrix to operate on.
- * @param[in] col The new number of column to clear.
+ * @param[in] col The column number to clear.
  *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered successful if column
- *     had no cells filled. Failure is asking for clear column outside
- *     matrix size.
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure (such as
+ *     requesting a column outside the matrix's defined size). It is
+ *     considered successful if the column had no cells filled.
  *
  * @warning Cells, rows or columns are not reference counted and thus
- *     after this call any reference might be invalid if instance were
- *     freed.
+ *     references to freed instances may become invalid.
  */
 EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col);
 
 /**
- * @brief Clears (erases) cell given its indexes.
+ * @brief Clears (erases) cell at a given row, column position.
  *
- * Existing cell will be cleared with @c free_func() given to
+ * Existing cell will be cleared with the @c free_func() given to
  * eina_matrixsparse_new().
  *
  * @param[in,out] m The sparse matrix to operate on.
- * @param[in] row The new number of row to clear.
- * @param[in] col The new number of column to clear.
+ * @param[in] row The row number.
+ * @param[in] col The column number.
  *
- * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered successful if did not
- *     exist but index is inside matrix size.
+ * @return #EINA_TRUE on success, #EINA_FALSE on failure (such as
+ *     requesting a row or column outside the matrix's defined size). It
+ *     is considered successful if no cell existed at the otherwise
+ *     valid position.
  *
  * @warning Cells, rows or columns are not reference counted and thus
- *     after this call any reference might be invalid if instance were
- *     freed.
+ *     references to freed instances may become invalid.
  *
- * @note This call might delete container column and row if this cell was the
- * last remainder.
+ * @note This call might also free the column and/or row if this was the
+ * last remaining cell contained.
  */
 EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col);
 
 /**
  * @brief Clears (erases) cell given its reference.
  *
- * @param[in,out] cell The cell reference, must @b not be @c NULL.
+ * @param[in,out] cell The cell reference; must @b not be @c NULL.
  *
  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
  *
  * @warning Cells, rows or columns are not reference counted and thus
- *     after this call any reference might be invalid if instance were
- *     freed.
+ *     references to freed instances may become invalid.
  *
- * @note This call might delete container column and row if this cell was the
- * last remainder.
+ * @note This call might also free the column and/or row if this was the
+ * last remaining cell contained.
  */
 EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
 
-/* iterators */
+/* Iterators */
 
 /**
- * @brief Creates a new iterator over existing matrix cells.
+ * @brief Creates a new iterator over only the existing matrix cells.
  *
- * This is a cheap walk, it will just report existing cells and holes
- * in the sparse matrix will be ignored. That means the reported
- * indexes will not be sequential.
+ * This is a quick walk over the defined cells; the holes in the Sparse
+ * Matrix are skipped over, thus the returned entries will not have
+ * consecutive index numbers.
  *
- * The iterator data will be the cell reference, one may query current
- * position with eina_matrixsparse_cell_position_get() and cell value
- * with eina_matrixsparse_cell_data_get().
+ * The iterator's data element will be the current cell reference.  This
+ * cell's position and value can be retrieved with
+ * eina_matrixsparse_cell_position_get() and
+ * eina_matrixsparse_cell_data_get().
  *
- * @param[in] m The Sparse Matrix reference, must @b not be @c NULL.
+ * @param[in] m The Sparse Matrix reference; must @b not be @c NULL.
  * @return A new iterator.
  *
  * @warning If the matrix structure changes then the iterator becomes
@@ -365,21 +371,23 @@ EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
 /**
  * @brief Creates a new iterator over all matrix cells.
  *
- * Unlike eina_matrixsparse_iterator_new() this one will report all
- * matrix cells, even those that are still empty (holes). These will
- * be reported as dummy cells that contains no data.
+ * In contrast to eina_matrixsparse_iterator_new(), this routine iterates
+ * across all row and column positions in the matrix, returning dummy cells
+ * with no data where there are empty holes.
  *
- * Be aware that iterating a big matrix (1000x1000) will call your
- * function that number of times (1000000 times in that case) even if
- * your matrix have no elements at all!
+ * Be aware that since this iterates over all potential elements of a
+ * Sparse Matrix, not just the elements with actual data, this can result
+ * in a very large number of function calls.
  *
- * The iterator data will be the cell reference, one may query current
- * position with eina_matrixsparse_cell_position_get() and cell value
- * with eina_matrixsparse_cell_data_get(). If cell is empty then the
+ * The iterator's data element will be the current cell reference.  This
+ * cell's position and value can be retrieved with
+ * eina_matrixsparse_cell_position_get() and
+ * eina_matrixsparse_cell_data_get().  If the cell is empty then the
  * reference will be a dummy/placeholder, thus setting value with
- * eina_matrixsparse_cell_data_set() will leave pointer unreferenced.
+ * eina_matrixsparse_cell_data_set() will leave the pointer
+ * unreferenced.
  *
- * @param[in] m The Sparse Matrix reference, must @b not be @c NULL.
+ * @param[in] m The Sparse Matrix reference; must @b not be @c NULL.
  * @return A new iterator.
  *
  * @warning If the matrix structure changes then the iterator becomes