Doxygen cleanups/fixes.

Closes issue #10654, patch by snuffy


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@81560 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/astobj2.h

@@ -90,7 +90,7 @@ parameters. At the moment, this is done as follows:
     struct ao2_container *c;
 
     c = ao2_container_alloc(MAX_BUCKETS, my_hash_fn, my_cmp_fn);
-
+    \endcode
 where
 - MAX_BUCKETS is the number of buckets in the hash table,
 - my_hash_fn() is the (user-supplied) function that returns a
@@ -153,7 +153,7 @@ void ao2_bt(void);	/* backtrace */
  *
  * Allocates a struct astobj2 with sufficient space for the
  * user-defined structure.
- * \notes:
+ * \note
  * - storage is zeroed; XXX maybe we want a flag to enable/disable this.
  * - the refcount of the object just created is 1
  * - the returned pointer cannot be free()'d or realloc()'ed;
@@ -329,8 +329,9 @@ struct ao2_container;
  * We allocate space for a struct astobj_container, struct container
  * and the buckets[] array.
  *
- * \param my_hash_fn Pointer to a function computing a hash value.
- * \param my_cmp_fn Pointer to a function comparating key-value 
+ * \param n_buckets Number of buckets for hash
+ * \param hash_fn Pointer to a function computing a hash value.
+ * \param cmp_fn Pointer to a function comparating key-value 
  * 			with a string. (can be NULL)
  * \return A pointer to a struct container.
  *
@@ -354,7 +355,7 @@ int ao2_container_count(struct ao2_container *c);
  * Add an object to a container.
  *
  * \param c the container to operate on.
- * \param obj the object to be added.
+ * \param newobj the object to be added.
  * \return NULL on errors, other values on success.
  *
  * This function insert an object in a container according its key.
@@ -364,7 +365,7 @@ int ao2_container_count(struct ao2_container *c);
 void *ao2_link(struct ao2_container *c, void *newobj);
 void *ao2_unlink(struct ao2_container *c, void *newobj);
 
-/*! \struct Used as return value if the flag OBJ_MULTIPLE is set */
+/*! \brief Used as return value if the flag OBJ_MULTIPLE is set */
 struct ao2_list {
 	struct ao2_list *next;
 	void *obj;	/* pointer to the user portion of the object */

include/asterisk/audiohook.h

@@ -163,12 +163,12 @@ struct ast_frame *ast_audiohook_write_list(struct ast_channel *chan, struct ast_
 void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
 
 /*! \brief Lock an audiohook
- * \param audiohook Audiohook structure
+ * \param ah Audiohook structure
  */
 #define ast_audiohook_lock(ah) ast_mutex_lock(&(ah)->lock)
 
 /*! \brief Unlock an audiohook
- * \param audiohook Audiohook structure
+ * \param ah Audiohook structure
  */
 #define ast_audiohook_unlock(ah) ast_mutex_unlock(&(ah)->lock)
 

include/asterisk/devicestate.h

@@ -135,7 +135,7 @@ int ast_devstate_changed(enum ast_device_state state, const char *fmt, ...)
  * \brief Tells Asterisk the State for Device is changed
  *
  * \param state the new state of the device
- * \param fmt device name like a dial string with format parameters
+ * \param device device name like a dial string with format parameters
  *
  * The new state of the device will be sent off to any subscribers
  * of device states.  It will also be stored in the internal event

include/asterisk/features.h

@@ -53,7 +53,8 @@ struct ast_call_feature {
  * \param chan the channel to actually be parked
  * \param host the channel which will have the parked location read to.
  * \param timeout is a timeout in milliseconds
- * \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+ * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
+ * 
  * Park the channel chan, and read back the parked location to the host. 
  * If the call is not picked up within a specified period of time, 
  * then the call will return to the last step that it was in 
@@ -68,7 +69,8 @@ int ast_park_call(struct ast_channel *chan, struct ast_channel *host, int timeou
  * \param rchan the real channel to be parked
  * \param host the channel to have the parking read to.
  * \param timeout is a timeout in milliseconds
- * \param extout is a parameter to an int that will hold the parked location, or NULL if you want
+ * \param extout is a parameter to an int that will hold the parked location, or NULL if you want.
+ * 
  * Masquerade the channel rchan into a new, empty channel which is then parked with ast_park_call
  * \retval 0 on success.
  * \retval -1 on failure.

include/asterisk/sha1.h

@@ -47,23 +47,22 @@ enum
 #endif
 #define SHA1HashSize 20
 
-/*
- *  This structure will hold context information for the SHA-1
- *  hashing operation
- */
+/*!
+ * \brief This structure will hold context information for the SHA-1 hashing operation
+*/
 typedef struct SHA1Context
 {
-    uint32_t Intermediate_Hash[SHA1HashSize/4]; /* Message Digest  */
+    uint32_t Intermediate_Hash[SHA1HashSize/4]; /*! Message Digest  */
 
-    uint32_t Length_Low;            /* Message length in bits      */
-    uint32_t Length_High;           /* Message length in bits      */
+    uint32_t Length_Low;            /*!< Message length in bits      */
+    uint32_t Length_High;           /*!< Message length in bits      */
 
                                /* Index into message block array   */
-    uint32_t Message_Block_Index;	/* 8 bits actually suffice */
-    uint8_t Message_Block[64];      /* 512-bit message blocks      */
+    uint32_t Message_Block_Index;	/*!< 8 bits actually suffice */
+    uint8_t Message_Block[64];      /*!< 512-bit message blocks      */
 
-    int Computed;               /* Is the digest computed?         */
-    int Corrupted;             /* Is the message digest corrupted? */
+    int Computed;               /*!< Is the digest computed?         */
+    int Corrupted;             /*!< Is the message digest corrupted? */
 } SHA1Context;
 
 /*

include/asterisk/stringfields.h

@@ -144,7 +144,7 @@ int __ast_string_field_init(struct ast_string_field_mgr *mgr, size_t size,
   \param needed Amount of space needed for this field
   \param fields Pointer to the first entry of the field array
   \param num_fields Number of fields in the array
-  \return NULL on failure, an address for the field on success
+  \return NULL on failure, an address for the field on success.
 
   This function will allocate the requested amount of space from
   the field pool. If the requested amount of space is not available,
@@ -356,7 +356,7 @@ void __ast_string_field_index_build_va(struct ast_string_field_mgr *mgr,
 /*!
   \brief Free the stringfield storage pools attached to a structure
   \param x Pointer to a structure containing fields
-  \return nothing
+  \return nothing.
 
   After calling this macro, fields can no longer be accessed in
   structure; it should only be called immediately before freeing
@@ -373,7 +373,7 @@ void __ast_string_field_index_build_va(struct ast_string_field_mgr *mgr,
 /*!
   \brief Free the stringfields in a structure
   \param x Pointer to a structure containing fields
-  \return nothing
+  \return nothing.
 
   After calling this macro, the most recently allocated pool
   attached to the structure will be available for use by

include/asterisk/strings.h

@@ -238,14 +238,14 @@ int ast_true(const char *val);
 int ast_false(const char *val);
 
 /*
-  \brief Join an array of strings into a single string.
-  \param s the resulting string buffer
-  \param len the length of the result buffer, s
-  \param w an array of strings to join
-
-  This function will join all of the strings in the array 'w' into a single
-  string.  It will also place a space in the result buffer in between each
-  string from 'w'.
+ *  \brief Join an array of strings into a single string.
+ * \param s the resulting string buffer
+ * \param len the length of the result buffer, s
+ * \param w an array of strings to join.
+ *
+ * This function will join all of the strings in the array 'w' into a single
+ * string.  It will also place a space in the result buffer in between each
+ * string from 'w'.
 */
 void ast_join(char *s, size_t len, char * const w[]);