- remove some unnecessary extern keywords

- cleanups to doxygen formatted documentation


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

1 files changed, 401 insertions, 223 deletions

diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h
index 9fa5655a0..eccae45db 100644
--- a/include/asterisk/pbx.h
+++ b/include/asterisk/pbx.h
@@ -36,11 +36,12 @@ extern "C" {
 /*! Max length of an application */
 #define AST_MAX_APP	32
 
-/*! Special return values from applications to the PBX */
-#define AST_PBX_KEEPALIVE	10		/* Destroy the thread, but don't hang up the channel */
-#define AST_PBX_NO_HANGUP_PEER       11
+/*! Special return values from applications to the PBX { */
+#define AST_PBX_KEEPALIVE	10	/*!< Destroy the thread, but don't hang up the channel */
+#define AST_PBX_NO_HANGUP_PEER	11
+/*! } */
 
-/*! Special Priority for an hint */
+/*! Special Priority for a hint */
 #define PRIORITY_HINT	-1
 
 /*! Extension states */
@@ -100,97 +101,122 @@ struct ast_switch {
 };
 
 struct ast_timing {
-	int hastime;				/* If time construct exists */
-	unsigned int monthmask;			/* Mask for month */
-	unsigned int daymask;			/* Mask for date */
-	unsigned int dowmask;			/* Mask for day of week (mon-sun) */
-	unsigned int minmask[24];		/* Mask for minute */
+	int hastime;				/*!< If time construct exists */
+	unsigned int monthmask;			/*!< Mask for month */
+	unsigned int daymask;			/*!< Mask for date */
+	unsigned int dowmask;			/*!< Mask for day of week (mon-sun) */
+	unsigned int minmask[24];		/*!< Mask for minute */
 };
 
-extern int ast_build_timing(struct ast_timing *i, char *info);
-extern int ast_check_timing(struct ast_timing *i);
+int ast_build_timing(struct ast_timing *i, char *info);
+int ast_check_timing(struct ast_timing *i);
 
 struct ast_pbx {
-        int dtimeout;                                   /* Timeout between digits (seconds) */
-        int rtimeout;                                   /* Timeout for response
+        int dtimeout;                                   /*!< Timeout between digits (seconds) */
+        int rtimeout;                                   /*!< Timeout for response
 							   (seconds) */
 };
 
 
-/*! Register an alternative switch */
 /*!
+ * \brief Reigster an alternative switch
+ *
  * \param sw switch to register
+ *
  * This function registers a populated ast_switch structure with the
  * asterisk switching architecture.
- * It returns 0 on success, and other than 0 on failure
+ *
+ * \return 0 on success, and other than 0 on failure
  */
-extern int ast_register_switch(struct ast_switch *sw);
+int ast_register_switch(struct ast_switch *sw);
 
-/*! Unregister an alternative switch */
 /*!
+ * \brief Unregister an alternative switch
+ *
  * \param sw switch to unregister
+ * 
  * Unregisters a switch from asterisk.
- * Returns nothing
+ *
+ * \return nothing
  */
-extern void ast_unregister_switch(struct ast_switch *sw);
+void ast_unregister_switch(struct ast_switch *sw);
 
-/*! Look up an application */
 /*!
+ * \brief Look up an application
+ *
  * \param app name of the app
+ *
  * This function searches for the ast_app structure within
  * the apps that are registered for the one with the name
  * you passed in.
- * Returns the ast_app structure that matches on success, or NULL on failure
+ *
+ * \return the ast_app structure that matches on success, or NULL on failure
  */
-extern struct ast_app *pbx_findapp(const char *app);
+struct ast_app *pbx_findapp(const char *app);
 
-/*! executes an application */
 /*!
+ * \brief Execute an application
+ *
  * \param c channel to execute on
  * \param app which app to execute
  * \param data the data passed into the app
  * \param newstack stack pointer
+ *
  * This application executes an application on a given channel.  It
  * saves the stack and executes the given appliation passing in
  * the given data.
- * It returns 0 on success, and -1 on failure
+ *
+ * \return 0 on success, and -1 on failure
  */
 int pbx_exec(struct ast_channel *c, struct ast_app *app, void *data, int newstack);
 
-/*! Register a new context */
 /*!
+ * \brief Register a new context
+ *
  * \param extcontexts pointer to the ast_context structure pointer
  * \param name name of the new context
  * \param registrar registrar of the context
+ *
  * This will first search for a context with your name.  If it exists already, it will not
  * create a new one.  If it does not exist, it will create a new one with the given name
  * and registrar.
- * It returns NULL on failure, and an ast_context structure on success
+ *
+ * \return NULL on failure, and an ast_context structure on success
  */
 struct ast_context *ast_context_create(struct ast_context **extcontexts, const char *name, const char *registrar);
 
-/*! Merge the temporary contexts into a global contexts list and delete from the global list the ones that are being added */
 /*!
+ * \brief Merge the temporary contexts into a global contexts list and delete from the 
+ *        global list the ones that are being added
+ *
  * \param extcontexts pointer to the ast_context structure pointer
- * \param registrar of the context; if it's set the routine will delete all contexts that belong to that registrar; if NULL only the contexts that are specified in extcontexts
+ * \param registrar of the context; if it's set the routine will delete all contexts 
+ *        that belong to that registrar; if NULL only the contexts that are specified 
+ *        in extcontexts
  */
 void ast_merge_contexts_and_delete(struct ast_context **extcontexts, const char *registrar);
 
-/*! Destroy a context (matches the specified context (or ANY context if NULL) */
 /*!
+ * \brief Destroy a context (matches the specified context (or ANY context if NULL)
+ *
  * \param con context to destroy
  * \param registrar who registered it
+ *
  * You can optionally leave out either parameter.  It will find it
  * based on either the ast_context or the registrar name.
- * Returns nothing
+ *
+ * \return nothing
  */
 void ast_context_destroy(struct ast_context *con, const char *registrar);
 
-/*! Find a context */
 /*!
+ * \brief Find a context
+ *
  * \param name name of the context to find
+ *
  * Will search for the context with the given name.
- * Returns the ast_context on success, NULL on failure.
+ *
+ * \return the ast_context on success, NULL on failure.
  */
 struct ast_context *ast_context_find(const char *name);
 
@@ -200,113 +226,147 @@ enum ast_pbx_result {
 	AST_PBX_CALL_LIMIT = -2,
 };
 
-/*! Create a new thread and start the PBX (or whatever) */
 /*!
+ * \brief Create a new thread and start the PBX
+ *
  * \param c channel to start the pbx on
+ *
+ * See ast_pbx_run for a synchronous function to run the PBX in the
+ * current thread, as opposed to starting a new one.
+ *
  * \return Zero on success, non-zero on failure
  */
 enum ast_pbx_result ast_pbx_start(struct ast_channel *c);
 
-/*! Execute the PBX in the current thread */
 /*!
+ * \brief Execute the PBX in the current thread
+ *
  * \param c channel to run the pbx on
- * \return Zero on success, non-zero on failure
+ *
  * This executes the PBX on a given channel. It allocates a new
  * PBX structure for the channel, and provides all PBX functionality.
+ * See ast_pbx_start for an asynchronous function to run the PBX in a
+ * new thread as opposed to the current one.
+ * 
+ * \return Zero on success, non-zero on failure
  */
 enum ast_pbx_result ast_pbx_run(struct ast_channel *c);
 
 /*! 
+ * \brief Add and extension to an extension context.  
+ * 
  * \param context context to add the extension to
  * \param replace
  * \param extension extension to add
  * \param priority priority level of extension addition
  * \param label extension label
- * \param callerid callerid of extension
+ * \param callerid pattern to match CallerID, or NULL to match any CallerID
  * \param application application to run on the extension with that priority level
  * \param data data to pass to the application
  * \param datad
  * \param registrar who registered the extension
- * Add and extension to an extension context.  
- * Callerid is a pattern to match CallerID, or NULL to match any callerid
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 success 
+ * \retval -1 failure
  */
-int ast_add_extension(const char *context, int replace, const char *extension, int priority, const char *label, const char *callerid,
+int ast_add_extension(const char *context, int replace, const char *extension, 
+	int priority, const char *label, const char *callerid,
 	const char *application, void *data, void (*datad)(void *), const char *registrar);
 
-/*! Add an extension to an extension context, this time with an ast_context *.  CallerID is a pattern to match on callerid, or NULL to not care about callerid */
 /*! 
- * For details about the arguements, check ast_add_extension()
+ * \brief Add an extension to an extension context, this time with an ast_context *.
+ *
+ * \note For details about the arguments, check ast_add_extension()
  */
-int ast_add_extension2(struct ast_context *con,
-				      int replace, const char *extension, int priority, const char *label, const char *callerid, 
-					  const char *application, void *data, void (*datad)(void *),
-					  const char *registrar);
+int ast_add_extension2(struct ast_context *con, int replace, const char *extension,
+	int priority, const char *label, const char *callerid, 
+	const char *application, void *data, void (*datad)(void *), const char *registrar);
 
-/*! Add an application.  The function 'execute' should return non-zero if the line needs to be hung up.  */
-/*!
-  \param app Short name of the application
-  \param execute a function callback to execute the application
-  \param synopsis a short description of the application
-  \param description long description of the application
-   Include a one-line synopsis (e.g. 'hangs up a channel') and a more lengthy, multiline
-   description with more detail, including under what conditions the application
-   will return 0 or -1.
-   This registers an application with asterisks internal application list.  Please note:
-   The individual applications themselves are responsible for registering and unregistering
-   CLI commands.
-   It returns 0 on success, -1 on failure.
-*/
+
+/*! 
+ * \brief Reigster an application.
+ *
+ * \param app Short name of the application
+ * \param execute a function callback to execute the application. It should return
+ *                non-zero if the channel needs to be hung up.
+ * \param synopsis a short description (one line synopsis) of the application
+ * \param description long description with all of the details about the use of 
+ *                    the application
+ * 
+ * This registers an application with Asterisk's internal application list. 
+ * \note The individual applications themselves are responsible for registering and unregistering
+ *       and unregistering their own CLI commands.
+ * 
+ * \retval 0 success 
+ * \retval -1 failure.
+ */
 int ast_register_application(const char *app, int (*execute)(struct ast_channel *, void *),
 			     const char *synopsis, const char *description);
 
-/*! Remove an application */
-/*!
+/*! 
+ * \brief Unregister an application
+ * 
  * \param app name of the application (does not have to be the same string as the one that was registered)
- * This unregisters an application from asterisk's internal registration mechanisms.
- * It returns 0 on success, and -1 on failure.
+ * 
+ * This unregisters an application from Asterisk's internal application list.
+ * 
+ * \retval 0 success 
+ * \retval -1 failure
  */
 int ast_unregister_application(const char *app);
 
-/*! Uses hint and devicestate callback to get the state of an extension */
-/*!
+/*! 
+ * \brief Uses hint and devicestate callback to get the state of an extension
+ *
  * \param c this is not important
  * \param context which context to look in
  * \param exten which extension to get state
- * Returns extension state !! = AST_EXTENSION_???
+ *
+ * \return extension state as defined in the ast_extension_states enum
  */
 int ast_extension_state(struct ast_channel *c, const char *context, const char *exten);
 
-/*! Return string of the state of an extension */
-/*!
+/*! 
+ * \brief Return string representation of the state of an extension
+ * 
  * \param extension_state is the numerical state delivered by ast_extension_state
- * Returns the state of an extension as string
+ *
+ * \return the state of an extension as string
  */
 const char *ast_extension_state2str(int extension_state);
 
-/*! Registers a state change callback */
 /*!
+ * \brief Registers a state change callback
+ * 
  * \param context which context to look in
  * \param exten which extension to get state
  * \param callback callback to call if state changed
  * \param data to pass to callback
- * The callback is called if the state for extension is changed
- * Return -1 on failure, ID on success
+ *
+ * The callback is called if the state of an extension is changed.
+ *
+ * \retval -1 on failure
+ * \retval ID on success
  */ 
 int ast_extension_state_add(const char *context, const char *exten, 
 			    ast_state_cb_type callback, void *data);
 
-/*! Deletes a registered state change callback by ID */
-/*!
+/*! 
+ * \brief Deletes a registered state change callback by ID
+ * 
  * \param id of the callback to delete
  * \param callback callback
+ *
  * Removes the callback from list of callbacks
- * Return 0 on success, -1 on failure
+ *
+ * \retval 0 success 
+ * \retval -1 failure
  */
 int ast_extension_state_del(int id, ast_state_cb_type callback);
 
-/*! If an extension exists, return non-zero */
-/*!
+/*! 
+ * \brief If an extension exists, return non-zero
+ * 
  * \param hint buffer for hint
  * \param maxlen size of hint buffer
  * \param name buffer for name portion of hint
@@ -314,233 +374,336 @@ int ast_extension_state_del(int id, ast_state_cb_type callback);
  * \param c this is not important
  * \param context which context to look in
  * \param exten which extension to search for
- * If an extension within the given context with the priority PRIORITY_HINT
+ *
+ * \return If an extension within the given context with the priority PRIORITY_HINT
  * is found a non zero value will be returned.
  * Otherwise, 0 is returned.
  */
-int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, struct ast_channel *c, const char *context, const char *exten);
+int ast_get_hint(char *hint, int maxlen, char *name, int maxnamelen, 
+	struct ast_channel *c, const char *context, const char *exten);
 
-/*! If an extension exists, return non-zero */
-/*  work */
 /*!
+ * \brief Determine whether an extension exists
+ *
  * \param c this is not important
  * \param context which context to look in
  * \param exten which extension to search for
  * \param priority priority of the action within the extension
  * \param callerid callerid to search for
- * If an extension within the given context(or callerid) with the given priority is found a non zero value will be returned.
- * Otherwise, 0 is returned.
+ *
+ * \return If an extension within the given context(or callerid) with the given priority 
+ *         is found a non zero value will be returned. Otherwise, 0 is returned.
  */
-int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
+int ast_exists_extension(struct ast_channel *c, const char *context, const char *exten, 
+	int priority, const char *callerid);
 
-/*! If an extension exists, return non-zero */
-/*  work */
-/*!
+/*! 
+ * \brief Find the priority of an extension that has the specified label
+ * 
  * \param c this is not important
  * \param context which context to look in
  * \param exten which extension to search for
  * \param label label of the action within the extension to match to priority
  * \param callerid callerid to search for
- * If an priority which matches given label in extension or -1 if not found.
-\ */
-int ast_findlabel_extension(struct ast_channel *c, const char *context, const char *exten, const char *label, const char *callerid);
-
-int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, const char *exten, const char *label, const char *callerid);
+ *
+ * \return the priority which matches the given label in the extension or -1 if not found.
+ */
+int ast_findlabel_extension(struct ast_channel *c, const char *context, 
+	const char *exten, const char *label, const char *callerid);
 
-/*! Looks for a valid matching extension */
 /*!
-  \param c not really important
-  \param context context to serach within
-  \param exten extension to check
-  \param priority priority of extension path
-  \param callerid callerid of extension being searched for
-   If "exten" *could be* a valid extension in this context with or without
-   some more digits, return non-zero.  Basically, when this returns 0, no matter
-   what you add to exten, it's not going to be a valid extension anymore
-*/
-int ast_canmatch_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
+ * \brief Find the priority of an extension that has the specified label
+ *
+ * \note This function is the same as ast_findlabel_extension, except that it accepts
+ * a pointer to an ast_context structure to specify the context instead of the
+ * name of the context. Otherwise, the functions behave the same.
+ */
+int ast_findlabel_extension2(struct ast_channel *c, struct ast_context *con, 
+	const char *exten, const char *label, const char *callerid);
 
-/*! Looks to see if adding anything to this extension might match something. (exists ^ canmatch) */
-/*!
-  \param c not really important
-  \param context context to serach within
-  \param exten extension to check
-  \param priority priority of extension path
-  \param callerid callerid of extension being searched for
-   If "exten" *could match* a valid extension in this context with
-   some more digits, return non-zero.  Does NOT return non-zero if this is
-   an exact-match only.  Basically, when this returns 0, no matter
-   what you add to exten, it's not going to be a valid extension anymore
-*/
-int ast_matchmore_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
+/*! 
+ * \brief Looks for a valid matching extension
+ * 
+ * \param c not really important
+ * \param context context to serach within
+ * \param exten extension to check
+ * \param priority priority of extension path
+ * \param callerid callerid of extension being searched for
+ *
+ * \return If "exten" *could be* a valid extension in this context with or without
+ * some more digits, return non-zero.  Basically, when this returns 0, no matter
+ * what you add to exten, it's not going to be a valid extension anymore
+ */
+int ast_canmatch_extension(struct ast_channel *c, const char *context, 
+	const char *exten, int priority, const char *callerid);
 
-/*! Determine if a given extension matches a given pattern (in NXX format) */
-/*!
+/*! 
+ * \brief Looks to see if adding anything to this extension might match something. (exists ^ canmatch)
+ *
+ * \param c not really important XXX
+ * \param context context to serach within
+ * \param exten extension to check
+ * \param priority priority of extension path
+ * \param callerid callerid of extension being searched for
+ *
+ * \return If "exten" *could match* a valid extension in this context with
+ * some more digits, return non-zero.  Does NOT return non-zero if this is
+ * an exact-match only.  Basically, when this returns 0, no matter
+ * what you add to exten, it's not going to be a valid extension anymore
+ */
+int ast_matchmore_extension(struct ast_channel *c, const char *context, 
+	const char *exten, int priority, const char *callerid);
+
+/*! 
+ * \brief Determine if a given extension matches a given pattern (in NXX format)
+ * 
  * \param pattern pattern to match
  * \param extension extension to check against the pattern.
+ *
  * Checks whether or not the given extension matches the given pattern.
- * Returns 1 on match, 0 on failure
+ *
+ * \retval 1 on match
+ * \retval 0 on failure
  */
 int ast_extension_match(const char *pattern, const char *extension);
+
 int ast_extension_close(const char *pattern, const char *data, int needmore);
-/*! Launch a new extension (i.e. new stack) */
-/*!
+
+/*! 
+ * \brief Launch a new extension (i.e. new stack)
+ * 
  * \param c not important
  * \param context which context to generate the extension within
  * \param exten new extension to add
  * \param priority priority of new extension
  * \param callerid callerid of extension
+ *
  * This adds a new extension to the asterisk extension list.
- * It returns 0 on success, -1 on failure.
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure.
  */
-int ast_spawn_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
+int ast_spawn_extension(struct ast_channel *c, const char *context, 
+	const char *exten, int priority, const char *callerid);
 
-/*! Execute an extension. */
-/*!
-  \param c channel to execute upon
-  \param context which context extension is in
-  \param exten extension to execute
-  \param priority priority to execute within the given extension
-  \param callerid Caller-ID
-   If it's not available, do whatever you should do for
-   default extensions and halt the thread if necessary.  This function does not
-   return, except on error.
-*/
-int ast_exec_extension(struct ast_channel *c, const char *context, const char *exten, int priority, const char *callerid);
+/*! 
+ * \brief Execute an extension.
+ * 
+ * \param c channel to execute upon
+ * \param context which context extension is in
+ * \param exten extension to execute
+ * \param priority priority to execute within the given extension
+ * \param callerid Caller-ID
+ *
+ * If it's not available, do whatever you should do for
+ * default extensions and halt the thread if necessary.  This function does not
+ * return, except on error.
+ */
+int ast_exec_extension(struct ast_channel *c, const char *context, 
+	const char *exten, int priority, const char *callerid);
 
-/*! Add an include */
-/*!
-  \param context context to add include to
-  \param include new include to add
-  \param registrar who's registering it
-   Adds an include taking a char * string as the context parameter
-   Returns 0 on success, -1 on error
+/*! 
+ * \brief Add a context include
+ *
+ * \param context context to add include to
+ * \param include new include to add
+ * \param registrar who's registering it
+ *
+ * Adds an include taking a char * string as the context parameter
+ *
+ * \retval 0 on success 
+ * \retval -1 on error
 */
-int ast_context_add_include(const char *context, const char *include, const char *registrar);
+int ast_context_add_include(const char *context, const char *include, 
+	const char *registrar);
 
-/*! Add an include */
-/*!
-  \param con context to add the include to
-  \param include include to add
-  \param registrar who registered the context
-   Adds an include taking a struct ast_context as the first parameter
-   Returns 0 on success, -1 on failure
-*/
-int ast_context_add_include2(struct ast_context *con, const char *include, const char *registrar);
+/*! 
+ * \brief Add a context include
+ * 
+ * \param con context to add the include to
+ * \param include include to add
+ * \param registrar who registered the context
+ *
+ * Adds an include taking a struct ast_context as the first parameter
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
+ */
+int ast_context_add_include2(struct ast_context *con, const char *include, 
+	const char *registrar);
 
-/*! Removes an include */
-/*!
- * See add_include
+/*! 
+ * \brief Remove a context include
+ * 
+ * \note See ast_context_add_include for information on arguments
+ *
+ * \retval 0 on success
+ * \retval -1 on failure
  */
-int ast_context_remove_include(const char *context, const char *include,const  char *registrar);
-/*! Removes an include by an ast_context structure */
-/*!
- * See add_include2
+int ast_context_remove_include(const char *context, const char *include, 
+	const char *registrar);
+
+/*! 
+ * \brief Removes an include by an ast_context structure 
+ * 
+ * \note See ast_context_add_include2 for information on arguments
+ *
+ * \retval 0 on success
+ * \retval -1 on success
  */
-int ast_context_remove_include2(struct ast_context *con, const char *include, const char *registrar);
+int ast_context_remove_include2(struct ast_context *con, const char *include, 
+	const char *registrar);
 
-/*! Verifies includes in an ast_contect structure */
-/*!
+/*! 
+ * \brief Verifies includes in an ast_contect structure
+ * 
  * \param con context in which to verify the includes
- * Returns 0 if no problems found, -1 if there were any missing context
+ *
+ * \retval 0 if no problems found 
+ * \retval -1 if there were any missing context
  */
 int ast_context_verify_includes(struct ast_context *con);
 	  
-/*! Add a switch */
-/*!
+/*! 
+ * \brief Add a switch
+ * 
  * \param context context to which to add the switch
  * \param sw switch to add
  * \param data data to pass to switch
  * \param eval whether to evaluate variables when running switch
  * \param registrar whoever registered the switch
+ *
  * This function registers a switch with the asterisk switch architecture
- * It returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
-int ast_context_add_switch(const char *context, const char *sw, const char *data, int eval, const char *registrar);
-/*! Adds a switch (first param is a ast_context) */
-/*!
- * See ast_context_add_switch()
+int ast_context_add_switch(const char *context, const char *sw, const char *data, 
+	int eval, const char *registrar);
+
+/*! 
+ * \brief Adds a switch (first param is a ast_context)
+ * 
+ * \note See ast_context_add_switch() for argument information, with the exception of
+ *       the first argument. In this case, it's a pointer to an ast_context structure
+ *       as opposed to the name.
  */
-int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, int eval, const char *registrar);
+int ast_context_add_switch2(struct ast_context *con, const char *sw, const char *data, 
+	int eval, const char *registrar);
 
-/*! Remove a switch */
-/*!
+/*! 
+ * \brief Remove a switch
+ * 
  * Removes a switch with the given parameters
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
-int ast_context_remove_switch(const char *context, const char *sw, const char *data, const char *registrar);
-int ast_context_remove_switch2(struct ast_context *con, const char *sw, const char *data, const char *registrar);
+int ast_context_remove_switch(const char *context, const char *sw, 
+	const char *data, const char *registrar);
 
-/*! Simply remove extension from context */
-/*!
+int ast_context_remove_switch2(struct ast_context *con, const char *sw, 
+	const char *data, const char *registrar);
+
+/*! 
+ * \brief Simply remove extension from context
+ * 
  * \param context context to remove extension from
  * \param extension which extension to remove
  * \param priority priority of extension to remove
  * \param registrar registrar of the extension
+ *
  * This function removes an extension from a given context.
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_context_remove_extension(const char *context, const char *extension, int priority,
 	const char *registrar);
+
 int ast_context_remove_extension2(struct ast_context *con, const char *extension,
 	int priority, const char *registrar);
 
-/*! Add an ignorepat */
-/*!
+/*! 
+ * \brief Add an ignorepat
+ * 
  * \param context which context to add the ignorpattern to
  * \param ignorepat ignorepattern to set up for the extension
  * \param registrar registrar of the ignore pattern
+ *
  * Adds an ignore pattern to a particular context.
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_context_add_ignorepat(const char *context, const char *ignorepat, const char *registrar);
+
 int ast_context_add_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
 
-/* Remove an ignorepat */
-/*!
+/* 
+ * \brief Remove an ignorepat
+ * 
  * \param context context from which to remove the pattern
  * \param ignorepat the pattern to remove
  * \param registrar the registrar of the ignore pattern
+ *
  * This removes the given ignorepattern
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_context_remove_ignorepat(const char *context, const char *ignorepat, const char *registrar);
+
 int ast_context_remove_ignorepat2(struct ast_context *con, const char *ignorepat, const char *registrar);
 
-/*! Checks to see if a number should be ignored */
-/*!
+/*! 
+ * \brief Checks to see if a number should be ignored
+ * 
  * \param context context to search within
  * \param pattern to check whether it should be ignored or not
- * Check if a number should be ignored with respect to dialtone cancellation.  
- * Returns 0 if the pattern should not be ignored, or non-zero if the pattern should be ignored 
+ *
+ * Check if a number should be ignored with respect to dialtone cancellation.
+ *
+ * \retval 0 if the pattern should not be ignored 
+ * \retval non-zero if the pattern should be ignored 
  */
 int ast_ignore_pattern(const char *context, const char *pattern);
 
 /* Locking functions for outer modules, especially for completion functions */
-/*! Locks the contexts */
-/*! Locks the context list
- * Returns 0 on success, -1 on error
+
+/*! 
+ * \brief Locks the context list
+ *
+ * \retval 0 on success 
+ * \retval -1 on error
  */
 int ast_lock_contexts(void);
 
-/*! Unlocks contexts */
-/*!
- * Returns 0 on success, -1 on failure
+/*! 
+ * \brief Unlocks contexts
+ * 
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_unlock_contexts(void);
 
-/*! Locks a given context */
-/*!
+/*! 
+ * \brief Locks a given context
+ * 
  * \param con context to lock
- * Locks the context.
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_lock_context(struct ast_context *con);
-/*! Unlocks the given context */
-/*!
+
+/*! 
+ * \retval Unlocks the given context
+ * 
  * \param con context to unlock
- * Unlocks the given context
- * Returns 0 on success, -1 on failure
+ *
+ * \retval 0 on success 
+ * \retval -1 on failure
  */
 int ast_unlock_context(struct ast_context *con);
 
@@ -549,11 +712,11 @@ int ast_async_goto(struct ast_channel *chan, const char *context, const char *ex
 
 int ast_async_goto_by_name(const char *chan, const char *context, const char *exten, int priority);
 
-/* Synchronously or asynchronously make an outbound call and send it to a
+/*! Synchronously or asynchronously make an outbound call and send it to a
    particular extension */
 int ast_pbx_outgoing_exten(const char *type, int format, void *data, int timeout, const char *context, const char *exten, int priority, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
 
-/* Synchronously or asynchronously make an outbound call and send it to a
+/*! Synchronously or asynchronously make an outbound call and send it to a
    particular application with given extension */
 int ast_pbx_outgoing_app(const char *type, int format, void *data, int timeout, const char *app, const char *appdata, int *reason, int sync, const char *cid_num, const char *cid_name, struct ast_variable *vars, const char *account, struct ast_channel **locked_channel);
 
@@ -593,21 +756,21 @@ struct ast_ignorepat *ast_walk_context_ignorepats(struct ast_context *con,
 struct ast_sw *ast_walk_context_switches(struct ast_context *con, struct ast_sw *sw);
 
 int pbx_builtin_serialize_variables(struct ast_channel *chan, char *buf, size_t size);
-extern const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
-extern void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
-extern void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
-extern void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
-extern void pbx_builtin_clear_globals(void);
-extern int pbx_builtin_setvar(struct ast_channel *chan, void *data);
-extern void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
-extern void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
+const char *pbx_builtin_getvar_helper(struct ast_channel *chan, const char *name);
+void pbx_builtin_pushvar_helper(struct ast_channel *chan, const char *name, const char *value);
+void pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value);
+void pbx_retrieve_variable(struct ast_channel *c, const char *var, char **ret, char *workspace, int workspacelen, struct varshead *headp);
+void pbx_builtin_clear_globals(void);
+int pbx_builtin_setvar(struct ast_channel *chan, void *data);
+void pbx_substitute_variables_helper(struct ast_channel *c,const char *cp1,char *cp2,int count);
+void pbx_substitute_variables_varshead(struct varshead *headp, const char *cp1, char *cp2, int count);
 
 int ast_extension_patmatch(const char *pattern, const char *data);
 
-/* Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
+/*! Set "autofallthrough" flag, if newval is <0, does not acutally set.  If
   set to 1, sets to auto fall through.  If newval set to 0, sets to no auto
   fall through (reads extension instead).  Returns previous value. */
-extern int pbx_set_autofallthrough(int newval);
+int pbx_set_autofallthrough(int newval);
 int ast_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
 /* I can find neither parsable nor parseable at dictionary.com, but google gives me 169000 hits for parseable and only 49,800 for parsable */
 int ast_parseable_goto(struct ast_channel *chan, const char *goto_string);
@@ -615,31 +778,46 @@ int ast_explicit_goto(struct ast_channel *chan, const char *context, const char
 int ast_async_goto_if_exists(struct ast_channel *chan, const char *context, const char *exten, int priority);
 
 struct ast_custom_function* ast_custom_function_find(const char *name);
+
+/*!
+ * \brief Unregister a custom function
+ */
 int ast_custom_function_unregister(struct ast_custom_function *acf);
+
+/*!
+ * \brief Reigster a custom function
+ */
 int ast_custom_function_register(struct ast_custom_function *acf);
 
-/* Number of active calls */
+/*! 
+ * \brief Retrieve the number of active calls
+ */
 int ast_active_calls(void);
 	
-/*! executes a read operation on a function */
 /*!
+ * \brief executes a read operation on a function 
+ *
  * \param chan Channel to execute on
  * \param function Data containing the function call string (will be modified)
  * \param workspace A pointer to safe memory to use for a return value 
  * \param len the number of bytes in workspace
+ *
+ * This application executes a function in read mode on a given channel.
+ *
  * \return zero on success, non-zero on failure
- * This application executes an function in read mode on a given channel.
- *  */
-	
+ */
 int ast_func_read(struct ast_channel *chan, char *function, char *workspace, size_t len);
 
-/*! executes a write operation on a function */
 /*!
+ * \brief executes a write operation on a function
+ *
  * \param chan Channel to execute on
  * \param function Data containing the function call string (will be modified)
  * \param value A value parameter to pass for writing
+ *
+ * This application executes a function in write mode on a given channel.
+ *
  * \return zero on success, non-zero on failure
- * This application executes an function in write mode on a given channel.
  */
 int ast_func_write(struct ast_channel *chan, char *function, const char *value);