From: Andre Noll <maan@tuebingen.mpg.de>
Date: Sat, 3 Jan 2015 22:57:58 +0000 (+0000)
Subject: Minor API documentation improvements.
X-Git-Tag: v0.1.3~18
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=9c3878f15dd44c830acc22f661e8585a62adb5ed;p=osl.git

Minor API documentation improvements.

A couple of spelling and punctuation fixes, and some language
improvements.
---

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
  */