Mailing-List: contact commits-help@apr.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@apr.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1032386 - /apr/apr/branches/1.4.x/include/apr_tables.h
Date: Sun, 07 Nov 2010 20:43:52 -0000
To: commits@apr.apache.org
From: sf@apache.org
Message-Id: <20101107204352.DD031238896F@eris.apache.org>

Author: sf
Date: Sun Nov  7 20:43:52 2010
New Revision: 1032386

URL: http://svn.apache.org/viewvc?rev=1032386&view=rev
Log:
Backport various documentation fixes from trunk, up to r1032383

Modified:
    apr/apr/branches/1.4.x/include/apr_tables.h

Modified: apr/apr/branches/1.4.x/include/apr_tables.h
URL: http://svn.apache.org/viewvc/apr/apr/branches/1.4.x/include/apr_tables.h?rev=1032386&r1=1032385&r2=1032386&view=diff
==============================================================================
--- apr/apr/branches/1.4.x/include/apr_tables.h (original)
+++ apr/apr/branches/1.4.x/include/apr_tables.h Sun Nov  7 20:43:52 2010
@@ -36,8 +36,8 @@ extern "C" {
 /**
  * @defgroup apr_tables Table and Array Functions
  * @ingroup APR 
- * Tables are used to store entirely opaque structures 
- * for applications, while Arrays are usually used to
+ * Arrays are used to store entirely opaque structures 
+ * for applications, while Tables are usually used to
  * deal with string lists.
  * @{
  */
@@ -81,28 +81,28 @@ struct apr_table_entry_t {
 };
 
 /**
- * Get the elements from a table
+ * Get the elements from a table.
  * @param t The table
  * @return An array containing the contents of the table
  */
 APR_DECLARE(const apr_array_header_t *) apr_table_elts(const apr_table_t *t);
 
 /**
- * Determine if the table is empty (either NULL or having no elements)
+ * Determine if the table is empty (either NULL or having no elements).
  * @param t The table to check
  * @return True if empty, False otherwise
  */
 APR_DECLARE(int) apr_is_empty_table(const apr_table_t *t);
 
 /**
- * Determine if the array is empty (either NULL or having no elements)
+ * Determine if the array is empty (either NULL or having no elements).
  * @param a The array to check
  * @return True if empty, False otherwise
  */
 APR_DECLARE(int) apr_is_empty_array(const apr_array_header_t *a);
 
 /**
- * Create an array
+ * Create an array.
  * @param p The pool to allocate the memory out of
  * @param nelts the number of elements in the initial array
  * @param elt_size The size of each element in the array.
@@ -112,7 +112,7 @@ APR_DECLARE(apr_array_header_t *) apr_ar
                                                  int nelts, int elt_size);
 
 /**
- * Add a new element to an array (as a first-in, last-out stack)
+ * Add a new element to an array (as a first-in, last-out stack).
  * @param arr The array to add an element to.
  * @return Location for the new element in the array.
  * @remark If there are no free spots in the array, then this function will
@@ -140,7 +140,7 @@ APR_DECLARE(void *) apr_array_push(apr_a
 #define APR_ARRAY_PUSH(ary,type) (*((type *)apr_array_push(ary)))
 
 /**
- * Remove an element from an array (as a first-in, last-out stack)
+ * Remove an element from an array (as a first-in, last-out stack).
  * @param arr The array to remove an element from.
  * @return Location of the element in the array.
  * @remark If there are no elements in the array, NULL is returned.
@@ -156,7 +156,7 @@ APR_DECLARE(void *) apr_array_pop(apr_ar
 APR_DECLARE(void) apr_array_clear(apr_array_header_t *arr);
 
 /**
- * Concatenate two arrays together
+ * Concatenate two arrays together.
  * @param dst The destination array, and the one to go first in the combined 
  *            array
  * @param src The source array to add to the destination array
@@ -165,7 +165,7 @@ APR_DECLARE(void) apr_array_cat(apr_arra
 			        const apr_array_header_t *src);
 
 /**
- * Copy the entire array
+ * Copy the entire array.
  * @param p The pool to allocate the copy of the array out of
  * @param arr The array to copy
  * @return An exact copy of the array passed in
@@ -198,7 +198,7 @@ APR_DECLARE(apr_array_header_t *) apr_ar
                                       const apr_array_header_t *second);
 
 /**
- * Generates a new string from the apr_pool_t containing the concatenated 
+ * Generate a new string from the apr_pool_t containing the concatenated 
  * sequence of substrings referenced as elements within the array.  The string 
  * will be empty if all substrings are empty or null, or if there are no 
  * elements in the array.  If sep is non-NUL, it will be inserted between 
@@ -213,7 +213,7 @@ APR_DECLARE(char *) apr_array_pstrcat(ap
 				      const char sep);
 
 /**
- * Make a new table
+ * Make a new table.
  * @param p The pool to allocate the pool out of
  * @param nelts The number of elements in the initial table.
  * @return The new table.
@@ -222,7 +222,7 @@ APR_DECLARE(char *) apr_array_pstrcat(ap
 APR_DECLARE(apr_table_t *) apr_table_make(apr_pool_t *p, int nelts);
 
 /**
- * Create a new table and copy another table into it
+ * Create a new table and copy another table into it.
  * @param p The pool to allocate the new table out of
  * @param t The table to copy
  * @return A copy of the table passed in
@@ -243,25 +243,25 @@ APR_DECLARE(apr_table_t *) apr_table_clo
                                            const apr_table_t *t);
 
 /**
- * Delete all of the elements from a table
+ * Delete all of the elements from a table.
  * @param t The table to clear
  */
 APR_DECLARE(void) apr_table_clear(apr_table_t *t);
 
 /**
  * Get the value associated with a given key from the table.  After this call,
- * The data is still in the table
+ * the data is still in the table.
  * @param t The table to search for the key
- * @param key The key to search for
+ * @param key The key to search for (case does not matter)
  * @return The value associated with the key, or NULL if the key does not exist. 
  */
 APR_DECLARE(const char *) apr_table_get(const apr_table_t *t, const char *key);
 
 /**
- * Add a key/value pair to a table, if another element already exists with the
- * same key, this will over-write the old data.
+ * Add a key/value pair to a table.  If another element already exists with the
+ * same key, this will overwrite the old data.
  * @param t The table to add the data to.
- * @param key The key to use
+ * @param key The key to use (case does not matter)
  * @param val The value to add
  * @remark When adding data, this function makes a copy of both the key and the
  *         value.
@@ -270,10 +270,10 @@ APR_DECLARE(void) apr_table_set(apr_tabl
                                 const char *val);
 
 /**
- * Add a key/value pair to a table, if another element already exists with the
- * same key, this will over-write the old data.
+ * Add a key/value pair to a table.  If another element already exists with the
+ * same key, this will overwrite the old data.
  * @param t The table to add the data to.
- * @param key The key to use
+ * @param key The key to use (case does not matter)
  * @param val The value to add
  * @warning When adding data, this function does not make a copy of the key or 
  *          the value, so care should be taken to ensure that the values will 
@@ -283,17 +283,18 @@ APR_DECLARE(void) apr_table_setn(apr_tab
                                  const char *val);
 
 /**
- * Remove data from the table
+ * Remove data from the table.
  * @param t The table to remove data from
- * @param key The key of the data being removed
+ * @param key The key of the data being removed (case does not matter)
  */
 APR_DECLARE(void) apr_table_unset(apr_table_t *t, const char *key);
 
 /**
  * Add data to a table by merging the value with data that has already been 
- * stored
+ * stored. The merging is done by concatenating the two values, separated
+ * by the string ", ".
  * @param t The table to search for the data
- * @param key The key to merge data for
+ * @param key The key to merge data for (case does not matter)
  * @param val The data to add
  * @remark If the key is not found, then this function acts like apr_table_add
  */
@@ -302,9 +303,10 @@ APR_DECLARE(void) apr_table_merge(apr_ta
 
 /**
  * Add data to a table by merging the value with data that has already been 
- * stored
+ * stored. The merging is done by concatenating the two values, separated
+ * by the string ", ".
  * @param t The table to search for the data
- * @param key The key to merge data for
+ * @param key The key to merge data for (case does not matter)
  * @param val The data to add
  * @remark If the key is not found, then this function acts like apr_table_addn
  */
@@ -331,13 +333,13 @@ APR_DECLARE(void) apr_table_add(apr_tabl
  * @param val The value to add.
  * @remark When adding data, this function does not make a copy of the key or the
  *         value, so care should be taken to ensure that the values will not 
- *         change after they have been added..
+ *         change after they have been added.
  */
 APR_DECLARE(void) apr_table_addn(apr_table_t *t, const char *key,
                                  const char *val);
 
 /**
- * Merge two tables into one new table
+ * Merge two tables into one new table.
  * @param p The pool to use for the new table
  * @param overlay The first table to put in the new table
  * @param base The table to add at the end of the new table
@@ -454,7 +456,7 @@ APR_DECLARE(void) apr_table_overlap(apr_
 
 /**
  * Eliminate redundant entries in a table by either overwriting
- * or merging duplicates
+ * or merging duplicates.
  *
  * @param t Table.
  * @param flags APR_OVERLAP_TABLES_MERGE to merge, or