Add doxygen documentation to string pool API

1 files changed, 79 insertions, 13 deletions

diff --git a/rpmio/rpmstrpool.h b/rpmio/rpmstrpool.h
index 1778c36ed..0db07bb40 100644
--- a/rpmio/rpmstrpool.h
+++ b/rpmio/rpmstrpool.h
@@ -7,40 +7,106 @@
 extern "C" {
 #endif
 
-/* XXX TODO: properly document... */
-
-/* create a new string pool */
+/** \ingroup rpmstrpool
+ * Create a new, empty string pool.
+ * @return		new string pool
+ */
 rpmstrPool rpmstrPoolCreate(void);
 
-/* destroy a string pool (refcounted) */
+/** \ingroup rpmstrpool
+ * Free a string pool and its contents. While other references exist,
+ * this only decrements the reference count.
+ * @param pool		string pool
+ * @return		NULL always
+ */
 rpmstrPool rpmstrPoolFree(rpmstrPool pool);
 
-/* reference a string pool */
+/** \ingroup rpmstrpool
+ * Reference a string pool
+ * @param pool		string pool
+ * @return		new string pool reference
+ */
 rpmstrPool rpmstrPoolLink(rpmstrPool pool);
 
-/* freeze pool to free memory (keephash required for string -> id lookups) */
+/** \ingroup rpmstrpool
+ * Freeze a string pool: new strings cannot be added to a frozen pool.
+ * If keephash is 0, memory usage is minimized but string -> id lookups
+ * are no longer possible and unfreezing is an expensive operation.
+ * Id -> string lookups are always possible on a frozen pool too.
+ * @param pool		string pool
+ * @param keephash	should string -> id hash be kept around?
+ */
 void rpmstrPoolFreeze(rpmstrPool pool, int keephash);
 
-/* unfreeze pool (ie recreate hash table) */
+/** \ingroup rpmstrpool
+ * Unfreeze a string pool to allow new additions again.
+ * If keephash was not specified on freezing, this requires rehashing
+ * the entire pool contents.
+ * @param pool		string pool
+ */
 void rpmstrPoolUnfreeze(rpmstrPool pool);
 
-/* get the id of a string, optionally storing if not already present */
+/** \ingroup rpmstrpool
+ * Look up the id of a string. If create is specified the string is
+ * added to the pool if it does not already exist. Creation can only
+ * fail if the pool is in frozen state.
+ * @param pool		string pool
+ * @param s		\0-terminated string to look up
+ * @param create	should an id be created if not already present?
+ * @return		id of the string or 0 for not found
+ */
 rpmsid rpmstrPoolId(rpmstrPool pool, const char *s, int create);
 
-/* get the id of a string + length, optionally storing if not already present */
+/** \ingroup rpmstrpool
+ * Look up the id of a string with predetermined length. The string does
+ * not have to be \0-terminated. If create is specified the string is
+ * added to the pool if it does not already exist. Creation can only
+ * fail if the pool is in frozen state. 
+ * @param pool		string pool
+ * @param s		string to look up
+ * @param slen		number of characters from s to consider
+ * @param create	should an id be created if not already present?
+ * @return		id of the string or 0 for not found
+ */
 rpmsid rpmstrPoolIdn(rpmstrPool pool, const char *s, size_t slen, int create);
 
-/* get a string by its id */
+/** \ingroup rpmstrpool
+ * Look up a string by its pool id.
+ * @param pool		string pool
+ * @param sid		pool id of a string
+ * @return		pointer to the string or NULL for invalid id
+ */
 const char * rpmstrPoolStr(rpmstrPool pool, rpmsid sid);
 
-/* get a strings length by its id (in constant time) */
+/** \ingroup rpmstrpool
+ * Return length of a string by its pool id. The result is equal to
+ * calling strlen() on a string retrieved through rpmstrPoolStr() but
+ * runs in constant time regardless of the length of the string.
+ * @param pool		string pool
+ * @param sid		pool id of a string
+ * @return		length of the string
+ */
 size_t rpmstrPoolStrlen(rpmstrPool pool, rpmsid sid);
 
-/* pool string equality comparison (constant time if within same pool) */
+/** \ingroup rpmstrpool
+ * Compare two strings for equality by their ids. The result is equal to
+ * calling rstreq() on two strings retrieved through rpmstrPoolStr() but
+ * when the id's are within the same pool, this runs in constant time.
+ * @param poolA		string pool of the first string
+ * @param sidA		pool id of the first string
+ * @param poolB		string pool of the second string
+ * @param sidB		pool id of the second string
+ * @return		1 if strings are equal, 0 otherwise
+ */
 int rpmstrPoolStreq(rpmstrPool poolA, rpmsid sidA,
                     rpmstrPool poolB, rpmsid sidB);
 
-/* get number of unique strings in pool */
+/** \ingroup rpmstrpool
+ * Return the number of strings stored in the pool. This number is
+ * also the highest legal id for the pool.
+ * @param pool		string pool
+ * @return		number of strings in the pool
+ */
 rpmsid rpmstrPoolNumStr(rpmstrPool pool);
 
 #ifdef __cplusplus