Fix a bunch of doxygen errors and document more things

(issue #9842, snuffy)


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

include/asterisk/devicestate.h

@@ -72,7 +72,7 @@ const char *devstate2str(enum ast_device_state devstate);
 const char *ast_devstate_str(enum ast_device_state devstate);
 
 /*! \brief Convert device state from text to integer value
- * \param The text representing the device state.  Valid values are anything
+ * \param val The text representing the device state.  Valid values are anything
  *        that comes after AST_DEVICE_ in one of the defined values.
  * \return The AST_DEVICE_ integer value
  */

include/asterisk/doxyref.h

@@ -16,7 +16,7 @@
  * at the top of the source tree.
  */
 
-/*! \file This file generates Doxygen pages from files in the /doc
+/*! \file doxyref.h This file generates Doxygen pages from files in the /doc
  directory of the Asterisk source code tree 
  */
 

include/asterisk/event.h

@@ -280,7 +280,7 @@ int ast_event_queue_and_cache(struct ast_event *event, ...);
 /*!
  * \brief Retrieve an event from the cache
  *
- * \param event_type The type of event to retrieve from the cache
+ * \param ast_event_type The type of event to retrieve from the cache
  *
  * The rest of the arguments to this function specify information elements to
  * match for retrieving events from the cache.  They are specified in the form:

include/asterisk/http.h

@@ -141,9 +141,11 @@ int ssl_setup(struct tls_config *cfg);
    return the content, allocated with malloc().  Status should be changed to reflect
    the status of the request if it isn't 200 and title may be set to a malloc()'d string
    to an appropriate title for non-200 responses.  Content length may also be specified. 
+\verbatim   
    The return value may include additional headers at the front and MUST include a blank 
    line with \r\n to provide separation between user headers and content (even if no
    content is specified) 
+\endverbatim
 */
 typedef struct ast_str *(*ast_http_callback)(struct sockaddr_in *requestor, const char *uri, struct ast_variable *params, int *status, char **title, int *contentlength);
 

include/asterisk/manager.h

@@ -35,11 +35,15 @@
  Manager protocol packages are text fields of the form a: b.  There is
  always exactly one space after the colon.
 
+\verbatim
+
  The first header type is the "Event" header.  Other headers vary from
  event to event.  Headers end with standard \r\n termination.
  The last line of the manager response or event is an empty line.
  (\r\n)
 
+\endverbatim
+
  ** Please try to re-use existing headers to simplify manager message parsing in clients.
     Don't re-use an existing header with a new meaning, please.
     You can find a reference of standard headers in doc/manager.txt

include/asterisk/stringfields.h

@@ -319,7 +319,8 @@ void __ast_string_field_index_build_va(struct ast_string_field_mgr *mgr,
   \param x Pointer to a structure containing fields
   \param field Name of the field to set
   \param fmt printf-style format string
-  \param argslist a va_list of the args
+  \param args1 arguement one
+  \param args2 arguement two
   \return nothing
 */
 #define ast_string_field_build_va(x, field, fmt, args1, args2) \

include/asterisk/strings.h

@@ -47,7 +47,7 @@ static force_inline int ast_strlen_zero(const char *s)
 /*!
   \brief Gets a pointer to the first non-whitespace character in a string.
   \param ast_skip_blanks function being used
-  \param str the input string
+  \arg str the input string
   \return a pointer to the first non-whitespace character
  */
 AST_INLINE_API(
@@ -61,8 +61,8 @@ char *ast_skip_blanks(const char *str),
 
 /*!
   \brief Trims trailing whitespace characters from a string.
-  \param ast_trim_blanks function being used
-  \param str the input string
+  \param ast_skip_blanks function being used
+  \arg str the input string
   \return a pointer to the modified string
  */
 AST_INLINE_API(
@@ -88,7 +88,7 @@ char *ast_trim_blanks(char *str),
 /*!
   \brief Gets a pointer to first whitespace character in a string.
   \param ast_skip_noblanks function being used
-  \param str the input string
+  \arg str the input string
   \return a pointer to the first whitespace character
  */
 AST_INLINE_API(
@@ -102,7 +102,8 @@ char *ast_skip_nonblanks(char *str),
   
 /*!
   \brief Strip leading/trailing whitespace from a string.
-  \param s The string to be stripped (will be modified).
+  \param ast_strip function ast_strip being used.
+  \arg s The string to be stripped (will be modified).
   \return The stripped string.
 
   This functions strips all leading and trailing whitespace
@@ -147,10 +148,9 @@ char *ast_strip_quoted(char *s, const char *beg_quotes, const char *end_quotes);
 
 /*!
   \brief Size-limited null-terminating string copy.
-  \param ast_copy_string function being used
-  \param dst The destination buffer.
-  \param src The source string
-  \param size The size of the destination buffer
+  \arg dst The destination buffer.
+  \arg src The source string
+  \arg size The size of the destination buffer
   \return Nothing.
 
   This is similar to \a strncpy, with two important differences:
@@ -183,9 +183,9 @@ void ast_copy_string(char *dst, const char *src, size_t size),
   This is a wrapper for snprintf, that properly handles the buffer pointer
   and buffer space available.
 
-  \param buffer current position in buffer to place string into (will be updated on return)
-  \param space remaining space in buffer (will be updated on return)
-  \param fmt printf-style format string
+  \arg buffer current position in buffer to place string into (will be updated on return)
+  \arg space remaining space in buffer (will be updated on return)
+  \arg fmt printf-style format string
   \return 0 on success, non-zero on failure.
 */
 int ast_build_string(char **buffer, size_t *space, const char *fmt, ...) __attribute__ ((format (printf, 3, 4)));