Merge a bunch of doxygen updates to header files. This includes changes to

use the \retval tag for documenting return values, fixing various warnings
when generating the documentation, and various other things.
(closes issue #10203, snuffy)


git-svn-id: http://svn.digium.com/svn/asterisk/trunk@75164 f38db490-d61c-443f-a65b-d21fe96a405b

1 files changed, 63 insertions, 55 deletions

diff --git a/include/asterisk/cdr.h b/include/asterisk/cdr.h
index df4860882..cdbf35e09 100644
--- a/include/asterisk/cdr.h
+++ b/include/asterisk/cdr.h
@@ -84,12 +84,12 @@ struct ast_cdr {
 	char accountcode[AST_MAX_ACCOUNT_CODE];			
 	/*! flags */
 	unsigned int flags;				
-	/* Unique Channel Identifier */
+	/*! Unique Channel Identifier */
 	char uniqueid[32];
-	/* User field */
+	/*! User field */
 	char userfield[AST_MAX_USER_FIELD];
 
-	/* A linked list for variables */
+	/*! A linked list for variables */
 	struct varshead varshead;
 
 	struct ast_cdr *next;
@@ -106,134 +106,141 @@ typedef int (*ast_cdrbe)(struct ast_cdr *cdr);
 /*! \brief Return TRUE if CDR subsystem is enabled */
 int check_cdr_enabled(void);
 
-/*! \brief Allocate a CDR record 
- * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
+/*! 
+ * \brief Allocate a CDR record 
+ * \retval a malloc'd ast_cdr structure
+ * \retval NULL on error (malloc failure)
  */
 struct ast_cdr *ast_cdr_alloc(void);
 
-/*! \brief Duplicate a record 
- * Returns a malloc'd ast_cdr structure, returns NULL on error (malloc failure)
+/*! 
+ * \brief Duplicate a record 
+ * \retval a malloc'd ast_cdr structure, 
+ * \retval NULL on error (malloc failure)
  */
 struct ast_cdr *ast_cdr_dup(struct ast_cdr *cdr);
 
-/*! \brief Free a CDR record 
+/*! 
+ * \brief Free a CDR record 
  * \param cdr ast_cdr structure to free
  * Returns nothing
  */
 void ast_cdr_free(struct ast_cdr *cdr);
 
-/*! \brief Discard and free a CDR record 
+/*! 
+ * \brief Discard and free a CDR record 
  * \param cdr ast_cdr structure to free
  * Returns nothing  -- same as free, but no checks or complaints
  */
 void ast_cdr_discard(struct ast_cdr *cdr);
 
-/*! \brief Initialize based on a channel
+/*! 
+ * \brief Initialize based on a channel
  * \param cdr Call Detail Record to use for channel
  * \param chan Channel to bind CDR with
  * Initializes a CDR and associates it with a particular channel
- * Return is negligible.  (returns 0 by default)
+ * \return 0 by default
  */
 int ast_cdr_init(struct ast_cdr *cdr, struct ast_channel *chan);
 
-/*! Initialize based on a channel */
 /*! 
+ * \brief Initialize based on a channel 
  * \param cdr Call Detail Record to use for channel
  * \param chan Channel to bind CDR with
  * Initializes a CDR and associates it with a particular channel
- * Return is negligible.  (returns 0 by default)
+ * \return 0 by default
  */
 int ast_cdr_setcid(struct ast_cdr *cdr, struct ast_channel *chan);
 
-/*! Register a CDR handling engine */
-/*!
+/*! 
+ * \brief Register a CDR handling engine 
  * \param name name associated with the particular CDR handler
  * \param desc description of the CDR handler
  * \param be function pointer to a CDR handler
  * Used to register a Call Detail Record handler.
- * Returns -1 on error, 0 on success.
+ * \retval 0 on success.
+ * \retval -1 on error
  */
 int ast_cdr_register(const char *name, const char *desc, ast_cdrbe be);
 
-/*! Unregister a CDR handling engine */
-/*!
+/*! 
+ * \brief Unregister a CDR handling engine 
  * \param name name of CDR handler to unregister
  * Unregisters a CDR by it's name
  */
 void ast_cdr_unregister(const char *name);
 
-/*! Start a call */
-/*!
+/*! 
+ * \brief Start a call 
  * \param cdr the cdr you wish to associate with the call
  * Starts all CDR stuff necessary for monitoring a call
  * Returns nothing
  */
 void ast_cdr_start(struct ast_cdr *cdr);
 
-/*! Answer a call */
-/*!
+/*! \brief Answer a call 
  * \param cdr the cdr you wish to associate with the call
  * Starts all CDR stuff necessary for doing CDR when answering a call
- * NULL argument is just fine.
+ * \note NULL argument is just fine.
  */
 void ast_cdr_answer(struct ast_cdr *cdr);
 
-/*! A call wasn't answered */
-/*!
+/*! 
+ * \brief A call wasn't answered 
  * \param cdr the cdr you wish to associate with the call
  * Marks the channel disposition as "NO ANSWER"
  */
 extern void ast_cdr_noanswer(struct ast_cdr *cdr);
 
-/*! Busy a call */
-/*!
+/*! 
+ * \brief Busy a call 
  * \param cdr the cdr you wish to associate with the call
  * Returns nothing
  */
 void ast_cdr_busy(struct ast_cdr *cdr);
 
-/*! Fail a call */
-/*!
+/*! 
+ * \brief Fail a call 
  * \param cdr the cdr you wish to associate with the call
  * Returns nothing
  */
 void ast_cdr_failed(struct ast_cdr *cdr);
 
-/*! Save the result of the call based on the AST_CAUSE_* */
-/*!
+/*! 
+ * \brief Save the result of the call based on the AST_CAUSE_*
  * \param cdr the cdr you wish to associate with the call
- * Returns nothing
  * \param cause the AST_CAUSE_*
+ * Returns nothing
  */
 int ast_cdr_disposition(struct ast_cdr *cdr, int cause);
 	
-/*! End a call */
-/*!
+/*! 
+ * \brief End a call
  * \param cdr the cdr you have associated the call with
  * Registers the end of call time in the cdr structure.
  * Returns nothing
  */
 void ast_cdr_end(struct ast_cdr *cdr);
 
-/*! Detaches the detail record for posting (and freeing) either now or at a
- * later time in bulk with other records during batch mode operation */
 /*! 
+ * \brief Detaches the detail record for posting (and freeing) either now or at a
+ * later time in bulk with other records during batch mode operation.
  * \param cdr Which CDR to detach from the channel thread
  * Prevents the channel thread from blocking on the CDR handling
  * Returns nothing
  */
 void ast_cdr_detach(struct ast_cdr *cdr);
 
-/*! Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines */
-/*!
+/*! 
+ * \brief Spawns (possibly) a new thread to submit a batch of CDRs to the backend engines 
  * \param shutdown Whether or not we are shutting down
  * Blocks the asterisk shutdown procedures until the CDR data is submitted.
  * Returns nothing
  */
 void ast_cdr_submit_batch(int shutdown);
 
-/*! Set the destination channel, if there was one */
-/*!
+/*! 
+ * \brief Set the destination channel, if there was one 
  * \param cdr Which cdr it's applied to
  * \param chan Channel to which dest will be
  * Sets the destination channel the CDR is applied to
@@ -241,8 +248,8 @@ void ast_cdr_submit_batch(int shutdown);
  */
 void ast_cdr_setdestchan(struct ast_cdr *cdr, const char *chan);
 
-/*! Set the last executed application */
-/*!
+/*! 
+ * \brief Set the last executed application 
  * \param cdr which cdr to act upon
  * \param app the name of the app you wish to change it to
  * \param data the data you want in the data field of app you set it to
@@ -251,40 +258,41 @@ void ast_cdr_setdestchan(struct ast_cdr *cdr, const char *chan);
  */
 void ast_cdr_setapp(struct ast_cdr *cdr, char *app, char *data);
 
-/*! Convert a string to a detail record AMA flag */
-/*!
+/*! 
+ * \brief Convert a string to a detail record AMA flag 
  * \param flag string form of flag
  * Converts the string form of the flag to the binary form.
- * Returns the binary form of the flag
+ * \return the binary form of the flag
  */
 int ast_cdr_amaflags2int(const char *flag);
 
-/*! Disposition to a string */
-/*!
+/*! 
+ * \brief Disposition to a string 
  * \param disposition input binary form
  * Converts the binary form of a disposition to string form.
- * Returns a pointer to the string form
+ * \return a pointer to the string form
  */
 char *ast_cdr_disp2str(int disposition);
 
-/*! Reset the detail record, optionally posting it first */
-/*!
+/*! 
+ * \brief Reset the detail record, optionally posting it first 
  * \param cdr which cdr to act upon
  * \param flags |AST_CDR_FLAG_POSTED whether or not to post the cdr first before resetting it
  *              |AST_CDR_FLAG_LOCKED whether or not to reset locked CDR's
  */
 void ast_cdr_reset(struct ast_cdr *cdr, struct ast_flags *flags);
 
-/*! Flags to a string */
-/*!
+/*! 
+ * \brief Flags to a string 
  * \param flags binary flag
  * Converts binary flags to string flags
  * Returns string with flag name
  */
 char *ast_cdr_flags2str(int flags);
 
-/*! Move the non-null data from the "from" cdr to the "to" cdr
- * \param to   the cdr to get the goodies
+/*! 
+ * \brief Move the non-null data from the "from" cdr to the "to" cdr
+ * \param to the cdr to get the goodies
  * \param from the cdr to give the goodies
  */
 void ast_cdr_merge(struct ast_cdr *to, struct ast_cdr *from);
@@ -297,7 +305,7 @@ int ast_cdr_setuserfield(struct ast_channel *chan, const char *userfield);
 int ast_cdr_appenduserfield(struct ast_channel *chan, const char *userfield);
 
 
-/* Update CDR on a channel */
+/*! Update CDR on a channel */
 int ast_cdr_update(struct ast_channel *chan);