From 9c3878f15dd44c830acc22f661e8585a62adb5ed Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Sat, 3 Jan 2015 22:57:58 +0000 Subject: [PATCH] Minor API documentation improvements. A couple of spelling and punctuation fixes, and some language improvements. --- osl.h.in | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/osl.h.in b/osl.h.in index 90585bc..1e1ec96 100644 --- a/osl.h.in +++ b/osl.h.in @@ -42,7 +42,7 @@ enum osl_storage_type { OSL_DISK_STORAGE, /** * Objects for columns of this type are volatile: They are only stored - * in memory and are discarded once the table gets closed. + * in memory and are discarded when the table is closed. */ OSL_NO_STORAGE }; @@ -75,10 +75,10 @@ struct osl_row; /** * In order to build up an rbtree a compare function for the objects must be - * specified. Such a function always takes pointers to the two objects to be - * compared. It must return -1, zero, or 1, if the first argument is considered - * to be respectively less than, equal to, or greater than the second. If two - * members compare as equal, their order in the rbtree is undefined. + * provided. This function takes pointers to the two objects to be compared. It + * must return -1, zero, or 1, if the first argument is considered to be + * respectively less than, equal to, or greater than the second. If two members + * compare as equal, their order in the rbtree is undefined. */ typedef int osl_compare_func(const struct osl_object *obj1, const struct osl_object *obj2); @@ -95,14 +95,14 @@ typedef int osl_rbtree_loop_func(struct osl_row *row, void *data); * Describes one column of a osl table. */ struct osl_column_description { - /** One of the tree possible types of storage, \sa osl_storage_type. */ + /** One of the three possible types of storage, \sa osl_storage_type. */ uint16_t storage_type; /** Specifies further properties of the column, \sa osl_storage_flags. */ uint16_t storage_flags; /** * The column name determines the name of the directory where all data * for this column will be stored. Its hash is stored in the table - * header. This field is ignored if the storage type is \a NO_STORAGE + * header. This field is ignored if the storage type is \a NO_STORAGE. */ char *name; /** @@ -148,9 +148,10 @@ struct osl_table_description { /** Flags to be passed to \a osl_close_table(). */ enum osl_close_flags { /** - * The table header contains a "dirty" flag which specifies whether - * the table is currently open by another process. This flag specifies - * that the dirty flag should be cleared before closing the table. + * The table header contains a "dirty" flag which indicates whether the + * table is currently held open by another process. The \a + * OSL_MARK_CLEAN flag instructs libosl to clear the dirty flag when + * the table is closed. */ OSL_MARK_CLEAN = 1, /** @@ -221,7 +222,7 @@ int osl_get_row(const struct osl_table *t, unsigned col_num, const struct osl_object *obj, struct osl_row **result); /** - * Retrieve an object identified by row and column + * Retrieve an object identified by row and column. * * \param t Pointer to an open osl table. * \param row Pointer to the row. @@ -382,7 +383,7 @@ int osl_rbtree_loop_reverse(const struct osl_table *t, unsigned col_num, * If the \p OSL_RBTREE flag is set for \a col_num, you \b MUST call this * function in order to change the contents of an object, even for volatile or * mapped columns of constant size (which may be updated directly if \p - * OSL_RBTREE is not set). Otherwise the rbtree might become corrupted. + * OSL_RBTREE is not set). Otherwise the rbtree might become corrupt. * * \return Standard */ -- 2.39.2