From 025b54ce5264f4084856f049dacebd39fd100020 Mon Sep 17 00:00:00 2001 From: Bryce Harrington Date: Mon, 16 Apr 2018 11:20:21 -0700 Subject: [PATCH] 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 --- src/lib/eina/eina_matrixsparse.h | 192 ++++++++++++++++--------------- 1 file 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,13 +218,13 @@ 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. + * + * @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 existing value. - * - * @param[in,out] cell The cell reference, must @b not be @c NULL. - * @param[in] data New data to set. + * call @c free_func() on the existing value, if one exists. * * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL). * @@ -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