You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@apr.apache.org by sf...@apache.org on 2010/11/07 21:42:27 UTC
svn commit: r1032384 - /apr/apr/branches/1.5.x/include/apr_tables.h
Author: sf
Date: Sun Nov 7 20:42:27 2010
New Revision: 1032384
URL: http://svn.apache.org/viewvc?rev=1032384&view=rev
Log:
backport various documentation fixes from trunk, up to r1032383
Modified:
apr/apr/branches/1.5.x/include/apr_tables.h
Modified: apr/apr/branches/1.5.x/include/apr_tables.h
URL: http://svn.apache.org/viewvc/apr/apr/branches/1.5.x/include/apr_tables.h?rev=1032384&r1=1032383&r2=1032384&view=diff
==============================================================================
--- apr/apr/branches/1.5.x/include/apr_tables.h (original)
+++ apr/apr/branches/1.5.x/include/apr_tables.h Sun Nov 7 20:42:27 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