Add Doxygen comments for SLAPI attr, value, and valueset functions.

This adds Doxygen comment blocks to the public header file for the
attr, value, and valueset related fucntions and defines.

1 files changed, 1085 insertions, 4 deletions

diff --git a/ldap/servers/slapd/slapi-plugin.h b/ldap/servers/slapd/slapi-plugin.h
index 42b57100..d35c12ce 100644
--- a/ldap/servers/slapd/slapi-plugin.h
+++ b/ldap/servers/slapd/slapi-plugin.h
@@ -102,13 +102,71 @@ NSPR_API(PRUint32) PR_fprintf(struct PRFileDesc* fd, const char *fmt, ...)
  *
  * Note that the flag values 0x0010, 0x0020, 0x4000, and 0x8000 are reserved.
  */
+/**
+ * Flag indicating that an attribtue is single-valued.
+ *
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_SINGLE		0x0001	/* single-valued attribute */
+
+/**
+ * Flag indicating than an attribute is operational.
+ *
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_OPATTR		0x0002	/* operational attribute */
+
+/**
+ * Flag indicating than an attribute is read-only.
+ *
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_READONLY	0x0004	/* read from shipped config file */
+
+/**
+ * Flag indicating than an attribute is read-only.
+ *
+ *  This is an alias for #SLAPI_ATTR_FLAG_READONLY.
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_STD_ATTR	SLAPI_ATTR_FLAG_READONLY /* alias for read only */
+
+/**
+ * Flag indicating than an attribute is obsolete.
+ *
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_OBSOLETE	0x0040	/* an outdated definition */
+
+/**
+ * Flag indicating that an attribute is collective.
+ *
+ * \warning Collective attributes are not supported, so this
+ *          flag has no effect.
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_COLLECTIVE	0x0080	/* collective (not supported) */
+
+/**
+ * Flag indicating that an attribute is not modifiable over LDAP.
+ *
+ * \see slapi_attr_flag_is_set()
+ * \see slapi_attr_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_NOUSERMOD	0x0100	/* can't be modified over LDAP */
+
+/**
+ * Flag to indicate that the attribute value is normalized.
+ *
+ * \see slapi_value_set_flags()
+ * \see slapi_values_set_flags()
+ */
 #define SLAPI_ATTR_FLAG_NORMALIZED	0x0200	/* the attr value is normalized */
 
 /* operation flags */
@@ -2866,110 +2924,1133 @@ int slapi_rdn2typeval( char *rdn, char **type, struct berval *bv );
 char *slapi_dn_plus_rdn(const char *dn, const char *rdn);
 
 
-/* TODO - Pickup Doxygen work here */
 /*
  * thread safe random functions
  */
+/**
+ * Generate a pseudo-random integer with optional seed.
+ *
+ * \param seed A seed to use when generating the pseudo random number.
+ * \return A pseudo random number.
+ * \see slapi_rand()
+ * \see slapi_rand_array()
+ */
 int slapi_rand_r(unsigned int * seed);
+
+/* Generate a pseudo-random integer in an array.
+ *
+ * \param randx The array you want filled with the random number.
+ * \param len The length of the array you want filled with the random number.
+ * \see slapi_rand()
+ * \see slapi_rand_r()
+ */
 void slapi_rand_array(void *randx, size_t len);
+
+/**
+ * Generate a pseudo-random integer.
+ *
+ * \return A pseudo random number.
+ * \see slapi_rand_r()
+ * \see slapi_rand_array()
+ */
 int slapi_rand();
 
 
 /*
  * attribute routines
  */
+/**
+ * Create a new empty attribute.
+ *
+ * \return A pointer to the newly created attribute.
+ * \warning You must free the returned attribute using slapi_attr_free().
+ * \see slapi_attr_init()
+ * \see slapi_attr_dup()
+ * \see slapi_attr_free()
+ */
 Slapi_Attr *slapi_attr_new( void );
+
+/**
+ * Initializes an attribute with an attribute type.
+ *
+ * \param a The attribute to initialize.
+ * \param type The attribute type to set.
+ * \return A pointer to the initialized attribute.
+ */
 Slapi_Attr *slapi_attr_init(Slapi_Attr *a, const char *type);
+
+/**
+ * Frees an attribute from memory.
+ *
+ * \param a Address of a pointer to the attribute to be freed.
+ * \see slapi_attr_init()
+ * \see slapi_attr_dup()
+ * \see slapi_attr_new()
+ */
 void slapi_attr_free( Slapi_Attr **a );
+
+/**
+ * Make a copy of an attribute.
+ *
+ * \param attr The attribute to be duplicated.
+ * \return The newly created copy of the attribute.
+ * \warning You must free the returned attribute using slapi_attr_free().
+ * \see slapi_attr_new()
+ * \see slapi_attr_init()
+ * \see slapi_attr_free()
+ */
 Slapi_Attr *slapi_attr_dup(const Slapi_Attr *attr);
+
+/**
+ * Adds a value to an attribute.
+ *
+ * \param a The attribute that will contain the values.
+ * \param v Value to be added to the attribute.
+ * \return Always returns 0.
+ * \see slapi_attr_first_value()
+ * \see slapi_attr_next_value()
+ * \see slapi_attr_get_numvalues()
+ * \see slapi_attr_value_cmp()
+ * \see slapi_attr_value_find()
+ */
 int slapi_attr_add_value(Slapi_Attr *a, const Slapi_Value *v);
+
+/**
+ * Find syntax plugin associated with an attribute type.
+ *
+ * \param type Type of attribute for which you want to get the plugin.
+ * \param pi Address to receive a pointer to the plugin structure.
+ * \return \c 0 if successful.
+ * \return \c -1 if the plugin is not found.
+ * \see slapi_attr_get_type()
+ * \see slapi_attr_type_cmp()
+ * \see slapi_attr_types_equivalent()
+ * \see slapi_attr_basetype()
+ */
 int slapi_attr_type2plugin( const char *type, void **pi );
+
+/**
+ * Get the name of the attribute type from a specified attribute.
+ *
+ * \param attr Attribute for which you want to get the type.
+ * \param type Address to receive a pointer to the attribute type.
+ * \return Always returns \c 0.
+ * \warning Do not free the returned attribute type.  The type is a part
+ *       if the actual attribute data, not a copy.
+ * \see slapi_attr_type2plugin()
+ * \see slapi_attr_type_cmp()
+ * \see slapi_attr_types_equivalent()
+ * \see slapi_attr_basetype()
+ */
 int slapi_attr_get_type( Slapi_Attr *attr, char **type );
+
+/**
+ * Get the attribute type OID of a particular attribute.
+ *
+ * \param attr Attribute that contains the desired OID.
+ * \param oidp Address to receive a pointer to a copy of the
+ *        attribute type OID.
+ * \return \c 0 if the attribute type is found.
+ * \return \c -1 if the attribute type is not found.
+ * \warning The returned OID should be freed by calling the
+ *       slapi_ch_free_string() function.
+ * \see slapi_attr_get_syntax_oid_copy()
+ */
 int slapi_attr_get_oid_copy( const Slapi_Attr *attr, char **oidp );
+
+/*
+ * Get the syntax OID of a particular attribute.
+ *
+ * \param a Attribute that contains the desired OID.
+ * \param oidp Address to receive a pointer to a copy of the
+ *        syntax OID.
+ * \return \c 0 if the syntax OID is found.
+ * \return \c -1 if the syntax OID is not found.
+ * \warning The returned OID should be freed by calling the
+ *       slapi_ch_free_string() function.
+ * \see slapi_attr_get_oid_copy()
+ */
 int slapi_attr_get_syntax_oid_copy( const Slapi_Attr *a, char **oidp );
+
+/**
+ * Get the flags associated with a particular attribute.
+ *
+ * Valid flags are:
+ *     \arg #SLAPI_ATTR_FLAG_SINGLE
+ *     \arg #SLAPI_ATTR_FLAG_OPATTR
+ *     \arg #SLAPI_ATTR_FLAG_READONLY
+ *     \arg #SLAPI_ATTR_FLAG_OBSOLETE
+ *     \arg #SLAPI_ATTR_FLAG_COLLECTIVE
+ *     \arg #SLAPI_ATTR_FLAG_NOUSERMOD
+ *     \arg #SLAPI_ATTR_FLAG_NORMALIZED
+ *
+ * \param attr Attribute for which you want to get the flags.
+ * \param flags Address of an integer that you want to reveive the flags.
+ * \return \c Always returns 0.
+ * \see slapi_attr_flag_is_set()
+ */
 int slapi_attr_get_flags( const Slapi_Attr *attr, unsigned long *flags );
+
+/**
+ * Checks if certain flags are set for a particular attribute.
+ *
+ * Valid flags are:
+ *     \arg #SLAPI_ATTR_FLAG_SINGLE
+ *     \arg #SLAPI_ATTR_FLAG_OPATTR
+ *     \arg #SLAPI_ATTR_FLAG_READONLY
+ *     \arg #SLAPI_ATTR_FLAG_OBSOLETE
+ *     \arg #SLAPI_ATTR_FLAG_COLLECTIVE
+ *     \arg #SLAPI_ATTR_FLAG_NOUSERMOD
+ *     \arg #SLAPI_ATTR_FLAG_NORMALIZED
+ *
+ * \param attr Attribute that you want to check.
+ * \param flag Flags to check in the attribute.
+ * \return \c 1 if the specified flags are set.
+ * \return \c 0 if the specified flags are not set.
+ * \see slapi_attr_get_flags()
+ */
 int slapi_attr_flag_is_set( const Slapi_Attr *attr, unsigned long flag );
+
+/**
+ * Comare two values for a given attribute.
+ *
+ * \param attr Attribute used to determine how these values are compared; for
+ *        example, the syntax of the attribute may perform case-insensitive
+ *        comparisons.
+ * \param v1 Pointer to the \c berval structure containing the first value
+ *        that you want to compare.
+ * \param v2 Pointer to the \c berval structure containing the second value
+ *        that you want to compare.
+ * \return \c 0 if the values are equal.
+ * \return \c -1 if the values are not equal.
+ * \see slapi_attr_add_value()
+ * \see slapi_attr_first_value()
+ * \see slapi_attr_next_value()
+ * \see slapi_attr_get_numvalues()
+ * \see slapi_attr_value_find()
+ */
 int slapi_attr_value_cmp( const Slapi_Attr *attr, const struct berval *v1, const struct berval *v2 );
+
+/**
+ * Determine if an attribute contains a given value.
+ *
+ * \param a Attribute that you want to check.
+ * \param v Pointer to the \c berval structure containing the value for
+ *          which you want to search.
+ * \return \c 0 if the attribute contains the specified value.
+ * \return \c 01 if the attribute does not contain the specified value.
+ * \see slapi_attr_add_value()
+ * \see slapi_attr_first_value()
+ * \see slapi_attr_next_value()
+ * \see slapi_attr_get_numvalues()
+ * \see slapi_attr_value_cmp()
+ */
 int slapi_attr_value_find( const Slapi_Attr *a, const struct berval *v );
 
+/**
+ * Compare two attribute types.
+ *
+ * \param t1 Name of the first attribute type to compare.
+ * \param t2 Name of the second attribute type to compare.
+ * \param opt One of the following options:
+ *        \arg #SLAPI_TYPE_CMP_EXACT
+ *        \arg #SLAPI_TYPE_CMP_BASE
+ *        \arg #SLAPI_TYPE_CMP_SUBTYPE
+ * \return \c 0 if the type names are equal.
+ * \return A non-zero value if the type names are not equal.
+ * \see slapi_attr_type2plugin()
+ * \see slapi_attr_get_type()
+ * \see slapi_attr_types_equivalent()
+ * \see slapi_attr_basetype()
+ */
 int slapi_attr_type_cmp( const char *t1, const char *t2, int opt );
+
 /* Mode of operation (opt) values for slapi_attr_type_cmp() */
+/**
+ * Compare the types as-is.
+ *
+ * \see slapi_attr_type_cmp()
+ */
 #define SLAPI_TYPE_CMP_EXACT	0
+
+/**
+ * Compare only the base names of the types.
+ *
+ * \see slapi_attr_type_cmp()
+ */
 #define SLAPI_TYPE_CMP_BASE	1
+
+/**
+ * Ignore any subtypes in the second type that are not in the first subtype.
+ *
+ * \see slapi_attr_type_cmp()
+ */
 #define SLAPI_TYPE_CMP_SUBTYPE	2
 
+/**
+ * Compare two attribute names to determine if they represent the same value.
+ *
+ * \param t1 Pointer to the first attribute you want to compare.
+ * \param t2 Pointer to the second attribute you want to compare.
+ * \return \c 1 if \c t1 and \c t2 represent the same attribute.
+ * \return \c 0 if \c t1 and \c t2 do not represent the same attribute.
+ * \see slapi_attr_type_cmp()
+ * \see slapi_attr_get_type()
+ * \see slapi_attr_basetype()
+ */
 int slapi_attr_types_equivalent(const char *t1, const char *t2);
+
+/**
+ * Get the base type of an attribute.
+ *
+ * For example, if given \c cn;lang-jp, returns \c cn.
+ *
+ * \param type Attribute type from which you want to get the base type.
+ * \param buf Buffer to hold the returned base type.
+ * \param bufsiz Size of the buffer.
+ * \return \c NULL if the base type fits in the buffer.
+ * \return A pointer to a newly allocated base type if the buffer is
+ *         too small to hold it.
+ * \warning If a base type is returned, if should be freed by calling
+ *          slapi_ch_free_string().
+ * \see slapi_attr_get_type()
+ * \see slapi_attr_type_cmp()
+ * \see slapi_attr_types_equivalent()
+ */
 char *slapi_attr_basetype( const char *type, char *buf, size_t bufsiz );
+
+/**
+ * Get the first value of an attribute.
+ *
+ * This is part of a set of functions to enumerate over a
+ * \c Slapi_Attr structure.
+ *
+ * \param a Attribute containing the desired value.
+ * \param v Holds the first value of the attribute.
+ * \return \c 0, which is the index of the first value.
+ * \return \c -1 if \c NULL or if the value is not found.
+ * \warning Do not free the returned value.  It is a part
+ *          of the attribute structure and not a copy.
+ * \see slapi_attr_next_value()
+ * \see slapi_attr_get_num_values()
+ */
 int slapi_attr_first_value( Slapi_Attr *a, Slapi_Value **v );
+
+/**
+ * Get the next value of an attribute.
+ *
+ * The value of an attribute associated with an index is placed into
+ * a value.  This is pare of a set of functions to enumerate over a
+ * \c Slapi_Attr structure.
+ *
+ * \param a Attribute containing the desired value.
+ * \param hint Index of the value to be returned.
+ * \param v Holds the value of the attribute.
+ * \return \c hint plus \c 1 if the value is found.
+ * \return \c -1 if \c NULL or if a value at \c hint is not found.
+ * \warning Do not free the returned value.  It is a part
+ *          of the attribute structure and not a copy.
+ * \see slapi_attr_first_value()
+ * \see slapi_attr_get_num_values()
+ */
 int slapi_attr_next_value( Slapi_Attr *a, int hint, Slapi_Value **v );
+
+/**
+ * Get the number of values present in an attribute.
+ *
+ * Counts the number of values in an attribute and places that
+ * count in an integer.
+ *
+ * \param a Attribute containing the values to be counted.
+ * \param numValues Integer to hold the counted values.
+ * \see slapi_attr_first_value()
+ * \see slapi_attr_next_value()
+ */
 int slapi_attr_get_numvalues( const Slapi_Attr *a, int *numValues);
+
+/**
+ * Copy existing values contained in an attribute into a valueset.
+ *
+ * \param a Attribute containing the values to be placed into
+ *        a valueset.
+ * \param vs Receives the values from the attribute.
+ * \return Always returns \c 0.
+ * \warning Free the returned valueset with slapi_valueset_free()
+ *          when finished using it.
+ * \see slapi_entry_add_valueset()
+ * \see slapi_valueset_new()
+ * \see slapi_valueset_free()
+ * \see slapi_valueset_init()
+ * \see slapi_valueset_done()
+ * \see slapi_valueset_add_value()
+ * \see slapi_valueset_first_value()
+ * \see slapi_valueset_next_value()
+ * \see slapi_valueset_count()
+ */
 int slapi_attr_get_valueset(const Slapi_Attr *a, Slapi_ValueSet **vs);
-/* Make the valuset in Slapi_Attr be *vs--not a copy */
+
+/**
+ * Sets the valueset in an attribute.
+ *
+ * Intializes a valueset in a \c Slapi_Attr structure from a specified
+ * \c Slapi_ValueSet structure.  The valueset in the \c Slapi_Attr
+ * will be \c vs, not a copy.
+ *
+ * \param a The attribute to set the valueset in.
+ * \param vs The valueset that you want to set in the attribute.
+ * \return Always returns \c 0.
+ * \warning Do not free \c vs.  Ownership of \c vs is tranferred to
+ *          the attribute.
+ * \see slapi_valueset_set_valueset()
+ */
 int slapi_attr_set_valueset(Slapi_Attr *a, const Slapi_ValueSet *vs);
+
+/**
+ * Set the attribute type of an attribute.
+ *
+ * \param a The attribute whose type you want to set.
+ * \param type The attribute type you want to set.
+ * \return \c 0 if the type was set.
+ * \return \c -1 if the type was not set.
+ * \warning The passed in type is copied, so ownership of \c type
+ *          remains with the caller.
+ * \see slapi_attr_get_type()
+ */
 int slapi_attr_set_type(Slapi_Attr *a, const char *type);
+
+/**
+ * Copy the values from an attribute into a berval array.
+ *
+ * \param a Attribute that contains the desired values.
+ * \param vals Pointer to an array of berval structure pointers to
+ *        hold the desired values.
+ * \return \c 0 if values are found.
+ * \return \c -1 if \c NULL.
+ * \warning You should free the array using ber_bvecfree() from the
+ *          Mozilla LDAP C SDK.
+ */
 int slapi_attr_get_bervals_copy( Slapi_Attr *a, struct berval ***vals );
+
+/**
+ * Normalize an attribute type.
+ *
+ * The attribute type will be looked up in the defined syntaxes to
+ * get the normalized form.  If it is not found, the passed in type
+ * will be normalized.
+ *
+ * \param s The attribute type that you want to normalize.
+ * \return A normalized copy of the passed in attribute type.
+ * \warning You should free the returned string using slapi_ch_free_string().
+ * \see slapi_ch_free_string()
+ */
 char * slapi_attr_syntax_normalize( const char *s );
-void slapi_valueset_set_valueset(Slapi_ValueSet *vs1, const Slapi_ValueSet *vs2);
-void slapi_valueset_set_from_smod(Slapi_ValueSet *vs, Slapi_Mod *smod);
 
 
 /*
  * value routines
  */
+/**
+ * Create a new empty \c Slapi_Value structure.
+ *
+ * \return A pointer to the newly allocated \c Slapi_Value structure.
+ * \warning If space can not be allocated, the \c ns-slapd program terminates.
+ * \warning When you are no longer using the value, free it from memory
+ *          by calling slapi_value_free()
+ * \see slapi_value_free()
+ * \see slapi_value_dup()
+ * \see slapi_value_new_berval()
+ * \see slapi_value_new_string()
+ * \see slapi_value_new_string_passin()
+ */
 Slapi_Value *slapi_value_new( void );
+
+/**
+ * Create a new \c Slapi_value structure and initialize it's value.
+ *
+ * \param bval Pointer to the \c berval structure used to initialize
+ *        the newly allocated \c Slapi_value.
+ * \return A pointer to the newly allocated and initialized value.
+ * \warning The passed in \c berval structure will be copied.  Ownership
+ *          of \c bval remains with the caller.
+ * \warning If space can not be allocated, the \c ns-slapd program terminates.
+ * \warning When you are no longer using the value, free it from memory
+ *          by calling slapi_value_free()
+ * \see slapi_value_free()
+ * \see slapi_value_new()
+ * \see slapi_value_new_string()
+ * \see slapi_value_new_string_passin()
+ * \see slapi_value_dup()
+ */
 Slapi_Value *slapi_value_new_berval(const struct berval *bval);
+
+/**
+ * Duplicate a \c Slapi_Value structure.
+ *
+ * \param v The value to duplicate.
+ * \return A pointer to the copy of the value.
+ * \warning If space can not be allocated, the \c ns-slapd program terminates.
+ * \warning When you are no longer using the value, free it from memory
+ *          by calling slapi_value_free()
+ * \warning This function is identical to slapi_value_dup().
+ * \see slapi_value_dup()
+ * \see slapi_value_free()
+ */
 Slapi_Value *slapi_value_new_value(const Slapi_Value *v);
+
+/**
+ * Create a new \c Slapi_value structure and initialize it's value.
+ *
+ * \param s A \c NULL terminated string used to initialize
+ *        the newly allocated \c Slapi_value.
+ * \return A pointer to the newly allocated and initialized value.
+ * \warning The passed in string will be copied.  Ownership of \c s
+ *          remains with the caller.
+ * \warning If space can not be allocated, the \c ns-slapd program terminates.
+ * \warning When you are no longer using the value, free it from memory
+ *          by calling slapi_value_free()
+ * \see slapi_value_free()
+ * \see slapi_value_new()
+ * \see slapi_value_new_berval()
+ \see slapi_value_new_string_passin()
+ * \see slapi_value_dup()
+ */
 Slapi_Value *slapi_value_new_string(const char *s);
+
+/**
+ * Create a new \c Slapi_value structure and initialize it's value.
+ *
+ * \param s A \c NULL terminated string used to initialize
+ *        the newly allocated \c Slapi_value.
+ * \return A pointer to the newly allocated and initialized value.
+ * \warning The passed in string will be used directly as the value.
+ *          It will not be copied.  Ownership of \c s is transferred
+ *          to the new \c Slapi_Value structure, so it should not be
+ *          freed by the caller.
+ * \warning If space can not be allocated, the \c ns-slapd program terminates.
+ * \warning When you are no longer using the value, free it from memory
+ *          by calling slapi_value_free()
+ * \see slapi_value_free()
+ * \see slapi_value_new()
+ * \see slapi_value_new_berval()
+ * \see slapi_value_new_string()
+ * \see slapi_value_dup()
+ */
 Slapi_Value *slapi_value_new_string_passin(char *s);
+
+/**
+ * Initialize a \c Slapi_Value structure.
+ *
+ * All fields of the passed in \c Slapi_Value will be reset to zero.
+ *
+ * \param v The value to initialize.
+ * \return A pointer to the initialized value.
+ * \warning The passed in value must not be \c NULL.
+ * \see slapi_value_init_berval()
+ * \see slapi_value_init_string()
+ * \see slapi_value_init_string_passin()
+ */
 Slapi_Value *slapi_value_init(Slapi_Value *v);
+
+/**
+ * Initialize a \c Slapi_Value structure from the value contained in a \c berval structure.
+ *
+ * \param v The value to initialize.
+ * \param bval The \c berval structure to be used to intialize the value.
+ * \return A pointer to the initialized value.
+ * \warning The passed in \c Slapi_Value must not be \c NULL.
+ * \warning The content of the \c berval structure is duplicated.  It is up
+ *          to the caller to manage the memory used by the \c berval.
+ * \see slapi_value_init()
+ * \see slapi_value_init_string()
+ * \see slapi_value_init_string_passin()
+ */
 Slapi_Value *slapi_value_init_berval(Slapi_Value *v, struct berval *bval);
+
+/**
+ * Initialize a \c Slapi_Value with a copy of the value contained in a string.
+ *
+ * \param v The value to initialize.
+ * \param s The null-terminated string to be used to initialize the value.
+ * \return A pointer to the initialized value.
+ * \warning The passed in \c Slapi_Value must not be \c NULL.
+ * \warning The passed in string is duplicated.  It is up to the caller to
+ *          manage the memory used by the passed in string.
+ * \see slapi_value_init()
+ * \see slapi_value_init_berval()
+ * \see slapi_value_init_string_passin()
+ */
 Slapi_Value *slapi_value_init_string(Slapi_Value *v,const char *s);
+
+/* Initialize a \c Slapi_Value with the value contained in a string.
+ *
+ * \param v The value to initialize.
+ * \param s The null-terminated string to be used to initialize the value.
+ * \return A pointer to the initialized value.
+ * \warning The passed in \c Slapi_Value must not be \c NULL.
+ * \warning The passed in string is not duplicated.  Responsibility for the
+ *          memory used by the string is handed over to the \c Slapi_Value
+ *          structure.
+ * \warning The passed in string must not be freed.  It will be freed when
+ *          the \c Slapi_Value structure is freed by calling \c slapi_value_free().
+ * \see slapi_value_free()
+ * \see slapi_value_init()
+ * \see slapi_value_init_berval()
+ * \see slapi_value_init_string()
+ */
 Slapi_Value *slapi_value_init_string_passin(Slapi_Value *v, char *s);
+
+/**
+ * Duplicate a \c Slapi_Value structure.
+ *
+ * \param v The value to duplicate.
+ * \return A pointer to the copy of the value.
+ * \warning If space can not be allocated, the \c ns-slapd program terminates.
+ * \warning When you are no longer using the value, free it from memory
+ *          by calling slapi_value_free()
+ * \warning This function is identical to slapi_value_new_value().
+ * \see slapi_value_new_value()
+ * \see slapi_value_free()
+ */
 Slapi_Value *slapi_value_dup(const Slapi_Value *v);
+
+/**
+ * Sets the flags in a \c Slapi_Value structure.
+ *
+ * Valid flags are:
+ *     \arg #SLAPI_ATTR_FLAG_NORMALIZED
+ *
+ * \param v Pointer to the \c Slapi_Value structure for which to
+ *        set the flags.
+ * \param flags The flags you want to set.
+ * \warning The flags support bit-wise operations.
+ * \see slapi_values_set_flags()
+ * \see slapi_value_get_flags()
+ */
 void slapi_value_set_flags(Slapi_Value *v, unsigned long flags);
+
+/**
+ * Sets the flags in an array of \c Slapi_Value structures.
+ *
+ * Valid flags are:
+ *     \arg #SLAPI_ATTR_FLAG_NORMALIZED
+ *
+ * \param vs Pointer to the \c Slapi_Value array for which you
+ *        want to set the flags.
+ * \param flags The flags you want to set.
+ * \warning The flags support bit-wise operations.
+ * \see slapi_value_set_flags()
+ * \see slapi_value_get_flags()
+ */
 void slapi_values_set_flags(Slapi_Value **vs, unsigned long flags);
+
+/**
+ * Retrieves the flags from a \c Slapi_Value structure.
+ *
+ * \param v Pointer to the \c Slapi_Value structure from which the
+ *       flags are to be retrieved.
+ * \return The flags that are set in the value.
+ * \see slapi_value_set_flags()
+ * \see slapi_values_set_flags()
+ */
 unsigned long slapi_value_get_flags(Slapi_Value *v);
+
+/**
+ * Frees a \c Slapi_Value structure from memory.
+ *
+ * The contents of the value will be freed along with the \c Slapi_Value
+ * structure itself.  The pointer will also be set to \c NULL.
+ *
+ * \param value Address of the pointer to the \c Slapi_Value structure
+ *        you wish to free.
+ * \see slapi_value_new()
+ */
 void slapi_value_free(Slapi_Value **value);
+
+/**
+ * Gets the \c berval structure of the value.
+ *
+ * \param value Pointer to the \c Slapi_Value of which you wish
+ *        to get the \c berval.
+ * \return A pointer to the \c berval structure contained in the
+ *         \c Slapi_Value.
+ * \warning The returned pointer point to the actual \c berval structure
+ *          inside of the value, not a copy.
+ * \warning You should not free the returned \c berval structure unless
+ *          you plan to replace it by calling \c slapi_value_set_berval().
+ * \see slapi_value_set_berval()
+ */
 const struct berval *slapi_value_get_berval( const Slapi_Value *value );
+
+/**
+ * Sets the value of a \c Slapi_Value structure from a \c berval structure.
+ *
+ * The value is duplicated from the passed in \c berval structure.
+ *
+ * \param value Pointer to the \c Slapi_Value structure in which to
+ *        set the value.
+ * \param bval Pointer to the \c berval value to be copied.
+ * \return Pointer to the \c Slapi_Value structure passed in as \c value.
+ * \return NULL if the passed in value was \c NULL.
+ * \warning If the pointer to the \c Slapi_Value structure is \c NULL,
+ *          nothing is done, and the function returns \c NULL.
+ * \warning If the \c Slapi_Value structure already contains a value, it
+ *          is freed from memory before the new one is set.
+ * \warning When you are no longer using the \c Slapi_Value structure, you
+ *          should free it from memory by valling \c slapi_value_free().
+ * \see slapi_value_free()
+ * \see slapi_value_get_berval()
+ */
 Slapi_Value *slapi_value_set_berval( Slapi_Value *value, const struct berval *bval );
+
+/**
+ * Sets the value of a \c Slapi_Value structure from another \c Slapi_Value structure.
+ *
+ * The value is duplicated from the supplied \c Slapi_value structure.
+ *
+ * \param value Pointer to the \c Slapi_Value structure in which to set
+ *        the value.
+ * \param vfrom Pointer to the \c Slapi_Value structure from which to
+ *        get the value.
+ * \return Pointer to the \c Slapi_Value structure passed as the \c value paramter.
+ * \return \c NULL if the \c value parameter was \c NULL.
+ * \warning The \c vfrom parameter must not be \c NULL.
+ * \warning If the pointer to the \c Slapi_Value structure is \c NULL,
+ *          nothing is done, and the function returns \c NULL.
+ * \warning If the \c Slapi_Value structure already contains a value, it
+ *          is freed from memory before the new one is set.
+ * \warning When you are no longer using the \c Slapi_Value structure, you
+ *          should free it from memory by valling \c slapi_value_free().
+ * \see slapi_value_free()
+ */
 Slapi_Value *slapi_value_set_value( Slapi_Value *value, const Slapi_Value *vfrom);
+
+/**
+ * Sets the value of a \c Slapi_Value structure.
+ *
+ * The value is a duplicate of the data pointed to by \c val and the
+ * length \c len.
+ *
+ * \param value Pointer to the \c Slapi_Value structure in which to set
+ *        the value.
+ * \param val Pointer to the value.
+ * \param len Length of the value.
+ * \return Pointer to the \c Slapi_Value structure with the value set.
+ * \return \c NULL if the supplied \c Slapi_Value is \c NULL.
+ * \warning If the pointer to the \c Slapi_Value structure is \c NULL,
+ *          nothing is done, and the function returns \c NULL.
+ * \warning If the \c Slapi_Value structure already contains a value, it
+ *          is freed from memory before the new one is set.
+ * \warning When you are no longer using the \c Slapi_Value structure, you
+ *          should free it from memory by valling \c slapi_value_free().
+ * \see slapi_value_free()
+ */
 Slapi_Value *slapi_value_set( Slapi_Value *value, void *val, unsigned long len);
+
+/**
+ * Sets the value of a \c Slapi_Value structure from a string.
+ *
+ * The value is duplicated from a supplied string.
+ *
+ * \param value Pointer to the \c Slapi_Value structure in which to set
+ *        the value.
+ * \param strVal The string containing the value to set.
+ * \return \c 0 if the value is set.
+ * \return \c -1 if the pointer to the \c Slapi_Value is \c NULL.
+ * \warning If the pointer to the \c Slapi_Value structure is \c NULL,
+ *          nothing is done, and the function returns \c -1.
+ * \warning If the \c Slapi_Value structure already contains a value, it
+ *          is freed from memory before the new one is set.
+ * \warning When you are no longer using the \c Slapi_Value structure, you
+ *          should free it from memory by valling \c slapi_value_free().
+ * \see slapi_value_free()
+ * \see slapi_value_set_string_passin()
+ */
 int slapi_value_set_string(Slapi_Value *value, const char *strVal);
+
+/**
+ * Sets the value of a \c Slapi_Value structure from a string.
+ *
+ * The supplied string is used as the value within the \c Slapi_Value
+ * structure.
+ *
+ * \param value Pointer to the \c Slapi_Value structure in which to set
+ *        the value.
+ * \param strVal The string containing the value to set.
+ * \return \c 0 if the value is set.
+ * \return \c -1 if the pointer to the \c Slapi_Value is \c NULL.
+ * \warning Do not free the passed in string pointer to by \c strVal.
+ *          Responsibility for the memory used by the string is handed
+ *          over to the \c Slapi_Value structure.
+ * \warning When you are no longer using the \c Slapi_Value structure, you
+ *          should free it from memory by valling \c slapi_value_free().
+ * \see slapi_value_free()
+ * \see slapi_value_set_string()
+ */
 int slapi_value_set_string_passin(Slapi_Value *value, char *strVal);
+
+/**
+ * Sets the value of a \c Slapi_Value structure from an integer.
+ *
+ * \param value Pointer to the \c Slapi_Value structure in which to set
+ *        the value.
+ * \param intVal The integer containing the value to set.
+ * \return \c 0 if the value is set.
+ * \return \c -1 if the pointer to the \c Slapi_Value is \c NULL.
+ * \warning If the pointer to the \c Slapi_Value structure is \c NULL,
+ *          nothing is done, and the function returns \c -1.
+ * \warning If the \c Slapi_Value structure already contains a value, it
+ *          is freed from memory before the new one is set.
+ * \warning When you are no longer using the \c Slapi_Value structure, you
+ *          should free it from memory by valling \c slapi_value_free().
+ * \see slapi_value_free()
+ */
 int slapi_value_set_int(Slapi_Value *value, int intVal);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as a string.
+ *
+ * \param value Pointer to the value you wish to get as a string.
+ * \return A string containing the value.
+ * \return \c NULL if there is no value.
+ * \warning The returned string is the actual value, not a copy.  You
+ *          should not free the returned string unless you plan to
+ *          replace it by calling slapi_value_set_string().
+ * \see slapi_value_set_string()
+ */
 const char*slapi_value_get_string(const Slapi_Value *value);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as an integer.
+ *
+ * \param value Pointer to the value you wish to get as an integer.
+ * \return An integer that corresponds to the value stored in the
+ *         \c Slapi_Value structure.
+ * \return \c 0 if there is no value.
+ * \see slapi_value_get_uint()
+ * \see slapi_value_get_long()
+ * \see slapi_value_get_ulong()
+ * \see slapi_value_get_longlong()
+ * \see slapi_value_get_ulonglong()
+ */
 int slapi_value_get_int(const Slapi_Value *value);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as an unsigned integer.
+ *
+ * \param value Pointer to the value you wish to get as an unsigned integer.
+ * \return An unsigned integer that corresponds to the value stored in
+ *         the \c Slapi_Value structure.
+ * \return \c 0 if there is no value.
+ * \see slapi_value_get_int()
+ * \see slapi_value_get_long()
+ * \see slapi_value_get_ulong()
+ * \see slapi_value_get_longlong()
+ * \see slapi_value_get_ulonglong()
+ */
 unsigned int slapi_value_get_uint(const Slapi_Value *value);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as a long integer.
+ *
+ * \param value Pointer to the value you wish to get as a long integer.
+ * \return A long integer that corresponds to the value stored in the
+ *         \c Slapi_Value structure.
+ * \return \c 0 if there is no value.
+ * \see slapi_value_get_int()
+ * \see slapi_value_get_uint()
+ * \see slapi_value_get_ulong()
+ * \see slapi_value_get_longlong()
+ * \see slapi_value_get_ulonglong()
+ */
 long slapi_value_get_long(const Slapi_Value *value);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as an unsigned long integer.
+ *
+ * \param value Pointer to the value you wish to get as an unsigned long integer.
+ * \return An unsigned long integer that corresponds to the value stored in the
+ *         \c Slapi_Value structure.
+ * \return \c 0 if there is no value.
+ * \see slapi_value_get_int()
+ * \see slapi_value_get_uint()
+ * \see slapi_value_get_long()
+ * \see slapi_value_get_longlong()
+ * \see slapi_value_get_ulonglong()
+ */
 unsigned long slapi_value_get_ulong(const Slapi_Value *value);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as a long long integer.
+ *
+ * \param value Pointer to the value you wish to get as a long long integer.
+ * \return A long long integer that corresponds to the value stored in the
+ *         \c Slapi_Value structure.
+ * \return \c 0 if there is no value.
+ * \see slapi_value_get_int()
+ * \see slapi_value_get_uint()
+ * \see slapi_value_get_long()
+ * \see slapi_value_get_ulong()
+ * \see slapi_value_get_ulonglong()
+ */
 long long slapi_value_get_longlong(const Slapi_Value *value);
+
+/**
+ * Retrieves the value of a \c Slapi_Value structure as an unsigned long long integer.
+ *
+ * \param value Pointer to the value you wish to get as an unsigned long long integer.
+ * \return An unsigned long long integer that corresponds to the value stored in the
+ *         \c Slapi_Value structure.
+ * \return \c 0 if there is no value.
+ * \see slapi_value_get_int()
+ * \see slapi_value_get_uint()
+ * \see slapi_value_get_long()
+ * \see slapi_value_get_ulong()
+ * \see slapi_value_get_longlong()
+ */
 unsigned long long slapi_value_get_ulonglong(const Slapi_Value *value);
+
+/**
+ * Gets the length of a value contained in a \c Slapi_Value structure.
+ *
+ * \param value Pointer to the value of which you wish to get the length.
+ * \return The length of the value.
+ * \return \c 0 if there is no value.
+ */
 size_t slapi_value_get_length(const Slapi_Value *value);
+
+/**
+ * Compares two \c Slapi_Value structures
+ * 
+ * The matching rule associated with the supplied attribute \c a is used
+ * to compare the two values.
+ *
+ * \param a A pointer to an attribute used to determine how the
+ *        two values will be compared.
+ * \param v1 Pointer to the \c Slapi_Value structure containing the first
+ *        value to compare.
+ * \param v2 Pointer to the \c Slapi_Value structure containing the second
+ *        value to compare.
+ * \return \c 0 if the two values are equal.
+ * \return \c -1 if \c v1 is smaller than \c v2.
+ * \return \c 1 if \c v1 is greater than \c v2.
+ */
 int slapi_value_compare(const Slapi_Attr *a,const Slapi_Value *v1,const Slapi_Value *v2);
 
 
 /*
  * Valueset functions.
  */
+
+/**
+ * Flag that indicates that the value should be used by reference.
+ *
+ * \see slapi_valueset_add_value_ext()
+ */
 #define SLAPI_VALUE_FLAG_PASSIN			0x1
 #define SLAPI_VALUE_FLAG_IGNOREERROR	0x2
 #define SLAPI_VALUE_FLAG_PRESERVECSNSET	0x4
 #define SLAPI_VALUE_FLAG_USENEWVALUE	0x8	/* see valueset_remove_valuearray */
 
+/**
+ * Creates an empty \c Slapi_ValueSet structure.
+ *
+ * \return Pointer to the newly allocated \c Slapi_ValueSet structure.
+ * \warning If no space can be allocated (for example, if no more virtual
+ *          memory exists), the \c ns-slapd program terminates.
+ * \warning When you are no longer using the valueset, you should free it
+ *          from memory by calling \c slapi_valueset_free().
+ * \see slapi_valueset_free()
+ */
 Slapi_ValueSet *slapi_valueset_new( void );
+
+/**
+ * Free a \c Slapi_ValueSet structure from memory.
+ *
+ * Call this function when you are done working with the structure.
+ * All members of the valueset will be freed as well if they are not
+ * \c NULL.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet to free.
+ * \see slapi_valueset_done()
+ */
 void slapi_valueset_free(Slapi_ValueSet *vs);
+
+/**
+ * Initializes a \c Slapi_ValueSet structure.
+ *
+ * All values inside of the structure will be cleared (set to \c 0).
+ * The values will not be freed by this function.  To free the values
+ * first, call \c slapi_valueset_done().
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet to initialize.
+ * \warning When you are no longer using the \c Slapi_ValueSet structure,
+ *          you should free it from memory by calling \c slapi_valueset_free().
+ * \see slapi_valueset_done()
+ * \see slapi_valueset_free()
+ */
 void slapi_valueset_init(Slapi_ValueSet *vs);
+
+/**
+ * Frees the values contained in a \c Slapi_ValueSet structure.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure from which
+ *        you want to free its values.
+ * \warning Use this function when you are no longer using the values
+ *          but you want to re-use the \c Slapi_ValueSet structure for
+ *          a new set of values.
+ * \see slapi_valueset_init()
+ */
 void slapi_valueset_done(Slapi_ValueSet *vs);
+
+/**
+ * Adds a value to a \c Slapi_ValueSet structure.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure to which to
+ *        add the value.
+ * \param addval Pointer to the \c Slapi_Value structure to add to
+ *        the \c Slapi_ValueSet.
+ * \warning The value is duplicated from the \c Slapi_Value structure,
+ *          which can be freed frmo memory without altering the
+ *          \c Slapi_ValueSet structure.
+ * \warning This function does not verify if the value is already present
+ *          in the \c Slapi_ValueSet structure.  You can manually check
+ *          this using \c slapi_valueset_first_value() and
+ *          \c slapi_valueset_next_value().
+ * \see slapi_valueset_first_value()
+ * \see slapi_valueset_next_value()
+ */
 void slapi_valueset_add_value(Slapi_ValueSet *vs, const Slapi_Value *addval);
+
+/**
+ * Adds a value to a \c Slapi_ValueSet structure with optional flags.
+ *
+ * This function is similar to \c slapi_valueset_add_value(), but it
+ * allows optional flags to be specified to allow the new value to be
+ * used by reference.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure to which to
+ *        add the value.
+ * \param addval Pointer to the \c Slapi_Value structure to add to
+ *        the \c Slapi_ValueSet.
+ * \param flags If #SLAPI_VALUE_FLAG_PASSIN bit is set in the flags,
+ *        the function will take over the ownership of the new value
+ *        to be added without duplicating it.
+ * \warning This function does not verify if the value is already present
+ *          in the \c Slapi_ValueSet structure.  You can manually check
+ *          this using \c slapi_valueset_first_value() and
+ *          \c slapi_valueset_next_value().
+ * \see slapi_valueset_add_value()
+ * \see slapi_valueset_first_value()
+ * \see slapi_valueset_next_value()
+ */
 void slapi_valueset_add_value_ext(Slapi_ValueSet *vs, Slapi_Value *addval, unsigned long flags);
+
+/**
+ * Gets the first value in a \c Slapi_ValueSet structure.
+ *
+ * This function can be used with \c slapi_valueset_next_value() to
+ * iterate through all values in a \c Slapi_ValueSet structure.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure from which
+ *        you wish to get the value.
+ * \param v Address of the pointer to the \c Slapi_Value structure
+ *        for the returned value.
+ * \return The index of the value in the Slapi_ValueSet structure.
+ * \return \c -1 if there was no value.
+ * \warning This function gives a pointer to the actual value within
+ *          the \c Slapi_ValueSet structure.  You should not free it
+ *          from memory.
+ * \warning You will need to pass this index to slapi_valueset_next_value()
+ *          if you wish to iterate through all values in the valueset.
+ * \see slapi_valueset_next_value().
+ */
 int slapi_valueset_first_value( Slapi_ValueSet *vs, Slapi_Value **v );
+
+/**
+ * Gets the next value in a \c Slapi_ValueSet structure.
+ *
+ * This is part of a pair of iterator functions.  It should be
+ * called after first calling \c slapi_valueset_first_value().
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure from which
+ *        you wish to get the value.
+ * \param index Value returned by the previous call to \c slapi_valueset_first_value()
+ *        or \c slapi_valueset_next_value().
+ * \param v Address of the pointer to the \c Slapi_Value structure
+ *        for the returned value.
+ * \return The index of the value in the Slapi_ValueSet structure.
+ * \return \c -1 if there was no value.
+ * \warning This function gives a pointer to the actual value within
+ *          the \c Slapi_ValueSet structure.  You should not free it
+ *          from memory.
+ * \warning You will need to pass this index to slapi_valueset_next_value()
+ *          if you wish to iterate through all values in the valueset.
+ * \see slapi_valueset_first_value()
+ */
 int slapi_valueset_next_value( Slapi_ValueSet *vs, int index, Slapi_Value **v);
+
+/**
+ * Returns the number of values contained in a \c Slapi_ValueSet structure.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure of which
+ *        you wish to get the count.
+ * \return The number of values contained in the \c Slapi_ValueSet structure.
+ */
 int slapi_valueset_count( const Slapi_ValueSet *vs);
+
+/**
+ * Initializes a \c Slapi_ValueSet with copies of the values of a \c Slapi_Mod structure.
+ *
+ * \param vs Pointer to the \c Slapi_ValueSet structure into which
+ *        you wish to copy the values.
+ * \param smod Pointer to the \c Slapi_Mod structure from which you
+ *        want to copy the values.
+ * \warning This function does not verify that the \c Slapi_ValueSet
+ *          structure already contains values, so it is your responsibility
+ *          to verify that there are no values prior to calling this function.
+ *          If you do not verify this, the allocated memory space will leak.
+ *          You can free existing values by calling slapi_valueset_done().
+ * \see slapi_valueset_done()
+ */
 void slapi_valueset_set_from_smod(Slapi_ValueSet *vs, Slapi_Mod *smod);
+
+/**
+ * Initializes a \c Slapi_ValueSet with copies of the values of another \c Slapi_ValueSet. 
+ *
+ * \param vs1 Pointer to the \c Slapi_ValueSet structure into which
+ *        you wish to copy the values.
+ * \param vs2 Pointer to the \c Slapi_ValueSet structure from which
+ *        you want to copy the values.
+ * \warning This function does not verify that the \c Slapi_ValueSet
+ *          structure already contains values, so it is your responsibility
+ *          to verify that there are no values prior to calling this function.
+ *          If you do not verify this, the allocated memory space will leak.
+ *          You can free existing values by calling slapi_valueset_done().
+ * \see slapi_valueset_done()
+ */
 void slapi_valueset_set_valueset(Slapi_ValueSet *vs1, const Slapi_ValueSet *vs2);
+
+/**
+ * Finds a requested value in a valueset.
+ *
+ * The syntax of a supplied attribute will be used to compare the values.
+ * This function can be used to check for duplicate values in a valueset.
+ *
+ * \param a Pointer to the attribute. This is used to determine the
+ *        syntax of the values and how to match them.
+ * \param vs Pointer to the \c Slapi_ValueSet structure from which
+ *        you wish to find the value.
+ * \param v Pointer to the \c Slapi_Value structure containing the
+ *        value that you wish to find.
+ * \return Pointer to the value in the valueset if the value was found.
+ * \return \c NULL if the value was not found.
+ * \warning The returned pointer points to the actual value in the
+ *          \c Slapi_ValueSet structure.  It should not be freed.
+ */
 Slapi_Value *slapi_valueset_find(const Slapi_Attr *a, const Slapi_ValueSet *vs, const Slapi_Value *v);
 
 
+/* TODO - Pickup Doxygen work here */
 /*
  * operation routines
  */