Doxygen Updates Janitor Work
authorAndrew Latham <lathama@gmail.com>
Sat, 22 Sep 2012 20:43:30 +0000 (20:43 +0000)
committerAndrew Latham <lathama@gmail.com>
Sat, 22 Sep 2012 20:43:30 +0000 (20:43 +0000)
* Whitespace, doc-blocks, spelling, case, missing and incorrect tags.
* Add cleanup to Makefile for the Doxygen configuration update
* Start updating Doxygen configuration for cleaner output
* Enable inclusion of configuration files into documentation
* remove mantisworkflow...
* update documentation README
* Add markup to Tilghman's email and talk with him about updating his email, he knows...
* no code changes on this commit other than the mentioned Makefile change

(issue ASTERISK-20259)

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

30 files changed:
Makefile
addons/chan_mobile.c
apps/app_minivm.c
apps/app_queue.c
apps/app_voicemail.c
cel/cel_odbc.c
cel/cel_sqlite3_custom.c
channels/chan_agent.c
channels/chan_mgcp.c
channels/chan_sip.c
codecs/speex/speex_resampler.h
contrib/asterisk-ng-doxygen
doc/README.txt
include/asterisk/doxygen/mantisworkflow.h [deleted file]
include/asterisk/doxyref.h
include/asterisk/format.h
include/asterisk/pbx.h
include/asterisk/xmpp.h
main/asterisk.c
main/astfd.c
main/audiohook.c
main/ccss.c
main/manager.c
main/pbx.c
main/xmldoc.c
res/res_config_pgsql.c
res/res_config_sqlite.c
res/res_timing_kqueue.c
tests/test_gosub.c
utils/refcounter.c

index 332091f..b75221b 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -746,6 +746,7 @@ progdocs:
        doxygen -u contrib/asterisk-ng-doxygen
        (cat contrib/asterisk-ng-doxygen; echo "HAVE_DOT=$(HAVEDOT)"; \
        echo "PROJECT_NUMBER=$(ASTERISKVERSION)") | doxygen -
+       rm -f contrib/asterisk-ng-doxygen.bak
 
 install-logrotate:
        if [ ! -d "$(DESTDIR)$(ASTETCDIR)/../logrotate.d" ]; then \
index be00221..454ebf1 100644 (file)
@@ -1524,8 +1524,8 @@ static int rfcomm_read_and_append_char(int rsock, char **buf, size_t count, size
 }
 
 /*!
- * \brief Read until '\r\n'.
- * This function consumes the '\r\n' but does not add it to buf.
+ * \brief Read until \verbatim '\r\n'. \endverbatim
+ * This function consumes the \verbatim'\r\n'\endverbatim but does not add it to buf.
  */
 static int rfcomm_read_until_crlf(int rsock, char **buf, size_t count, size_t *in_count)
 {
@@ -1552,7 +1552,7 @@ static int rfcomm_read_until_crlf(int rsock, char **buf, size_t count, size_t *i
 
 /*!
  * \brief Read the remainder of an AT SMS prompt.
- * \note the entire parsed string is '\r\n> '
+ * \note the entire parsed string is \verbatim '\r\n> ' \endverbatim
  *
  * By the time this function is executed, only a ' ' is left to read.
  */
@@ -1570,7 +1570,7 @@ e_return:
 }
 
 /*!
- * \brief Read until a \r\nOK\r\n message.
+ * \brief Read until a \verbatim \r\nOK\r\n \endverbatim message.
  */
 static int rfcomm_read_until_ok(int rsock, char **buf, size_t count, size_t *in_count)
 {
@@ -1667,7 +1667,7 @@ static int rfcomm_read_until_ok(int rsock, char **buf, size_t count, size_t *in_
 
 /*!
  * \brief Read the remainder of a +CMGR message.
- * \note the entire parsed string is '+CMGR: ...\r\n...\r\n...\r\n...\r\nOK\r\n'
+ * \note the entire parsed string is \verbatim '+CMGR: ...\r\n...\r\n...\r\n...\r\nOK\r\n' \endverbatim
  */
 static int rfcomm_read_cmgr(int rsock, char **buf, size_t count, size_t *in_count)
 {
@@ -1686,7 +1686,7 @@ static int rfcomm_read_cmgr(int rsock, char **buf, size_t count, size_t *in_coun
 
 /*!
  * \brief Read and AT result code.
- * \note the entire parsed string is '\r\n<result code>\r\n'
+ * \note the entire parsed string is \verbatim '\r\n<result code>\r\n' \endverbatim
  */
 static int rfcomm_read_result(int rsock, char **buf, size_t count, size_t *in_count)
 {
@@ -1724,7 +1724,7 @@ e_return:
 
 /*!
  * \brief Read the remainder of an AT command.
- * \note the entire parsed string is '<at command>\r'
+ * \note the entire parsed string is \verbatim '<at command>\r' \endverbatim
  */
 static int rfcomm_read_command(int rsock, char **buf, size_t count, size_t *in_count)
 {
@@ -1758,8 +1758,8 @@ static int rfcomm_read_command(int rsock, char **buf, size_t count, size_t *in_c
  * \endverbatim
  *
  * These formats correspond to AT result codes, AT commands, and the AT SMS
- * prompt respectively.  When messages are read the leading and trailing '\r'
- * and '\n' characters are discarded.  If the given buffer is not large enough
+ * prompt respectively.  When messages are read the leading and trailing \verbatim '\r' \endverbatim
+ * and \verbatim '\n' \endverbatim characters are discarded.  If the given buffer is not large enough
  * to hold the response, what does not fit in the buffer will be dropped.
  *
  * \note The rfcomm connection to the device is asynchronous, so there is no
@@ -2132,7 +2132,7 @@ static int hfp_parse_ciev(struct hfp_pvt *hfp, char *buf, int *value)
  * \brief Parse a CLIP event.
  * \param hfp an hfp_pvt struct
  * \param buf the buffer to parse (null terminated)
- * @note buf will be modified when the CID string is parsed
+ * \note buf will be modified when the CID string is parsed
  * \return NULL on error (parse error) or a pointer to the caller id
  * information in buf
  */
@@ -2178,7 +2178,7 @@ static char *hfp_parse_clip(struct hfp_pvt *hfp, char *buf)
  * \brief Parse a CMTI notification.
  * \param hfp an hfp_pvt struct
  * \param buf the buffer to parse (null terminated)
- * @note buf will be modified when the CMTI message is parsed
+ * \note buf will be modified when the CMTI message is parsed
  * \return -1 on error (parse error) or the index of the new sms message
  */
 static int hfp_parse_cmti(struct hfp_pvt *hfp, char *buf)
@@ -2203,7 +2203,7 @@ static int hfp_parse_cmti(struct hfp_pvt *hfp, char *buf)
  * \param from_number a pointer to a char pointer which will store the from
  * number
  * \param text a pointer to a char pointer which will store the message text
- * @note buf will be modified when the CMGR message is parsed
+ * \note buf will be modified when the CMGR message is parsed
  * \retval -1 parse error
  * \retval 0 success
  */
@@ -2266,7 +2266,7 @@ static int hfp_parse_cmgr(struct hfp_pvt *hfp, char *buf, char **from_number, ch
  * \brief Parse a CUSD answer.
  * \param hfp an hfp_pvt struct
  * \param buf the buffer to parse (null terminated)
- * @note buf will be modified when the CUSD string is parsed
+ * \note buf will be modified when the CUSD string is parsed
  * \return NULL on error (parse error) or a pointer to the cusd message
  * information in buf
  */
index f2ee5ee..e37346f 100644 (file)
@@ -26,7 +26,6 @@
  * based on the Comedian Mail voicemail system (app_voicemail.c).
  * 
  * \par See also
- * \arg \ref Config_minivm
  * \arg \ref Config_minivm_examples
  * \arg \ref App_minivm
  *
index a96d811..1de332f 100644 (file)
@@ -5799,8 +5799,9 @@ static struct member *interface_exists(struct call_queue *q, const char *interfa
 
 
 /*! \brief Dump all members in a specific queue to the database
- *
+ * \code
  * <pm_family>/<queuename> = <interface>;<penalty>;<paused>;<state_interface>[|...]
+ * \endcode
  */
 static void dump_queue_members(struct call_queue *pm_queue)
 {
index dee45c8..84fd181 100644 (file)
  * \author Mark Spencer <markster@digium.com>
  * \brief Comedian Mail - Voicemail System
  *
- * \extref unixODBC (http://www.unixodbc.org/)
- * \extref A source distribution of University of Washington's IMAP c-client
+ * unixODBC (http://www.unixodbc.org/)
+ * A source distribution of University of Washington's IMAP c-client
  *         (http://www.washington.edu/imap/)
  *
  * \par See also
  * \arg \ref Config_vm
  * \note For information about voicemail IMAP storage, https://wiki.asterisk.org/wiki/display/AST/IMAP+Voicemail+Storage
- * \ingroup applications
- * \note This module requires res_adsi to load. This needs to be optional
+  * \ingroup applications
+ * \todo This module requires res_adsi to load. This needs to be optional
  * during compilation.
  *
- * \note This file is now almost impossible to work with, due to all \#ifdefs.
+ * \todo This file is now almost impossible to work with, due to all \#ifdefs.
  *       Feels like the database code before realtime. Someone - please come up
  *       with a plan to clean this up.
  */
@@ -1053,7 +1053,7 @@ static int message_range_and_existence_check(struct vm_state *vms, const char *m
  *
  * \note the "move" parameter is only honored for IMAP voicemail presently
  * \retval 0 Success
- * \revval other Failure
+ * \retval other Failure
  */
 static int save_to_folder(struct ast_vm_user *vmu, struct vm_state *vms, int msg, int box, int *newmsg, int move);
 
@@ -4804,7 +4804,7 @@ static const char *ast_str_encode_mime(struct ast_str **end, ssize_t maxlen, con
  * \param chan
  * \param category
  * \param imap if == 1, indicates the target folder for the email notification to be sent to will be an IMAP mailstore. This causes additional mailbox headers to be set, which would facilitate searching for the email in the destination IMAP folder.
- * \param flag
+ * \param flag, msg_id
  *
  * The email body, and base 64 encoded attachement (if any) are stored to the file identified by *p. This method does not actually send the email.  That is done by invoking the configure 'mailcmd' and piping this generated file into it, or with the sendemail() function.
  */
@@ -5630,7 +5630,7 @@ static int has_voicemail(const char *mailbox, const char *folder)
  * \param recip
  * \param fmt
  * \param dir
- * \param flag
+ * \param flag, dest_folder
  *
  * This is only used by file storage based mailboxes.
  *
@@ -5746,7 +5746,7 @@ static int __has_voicemail(const char *context, const char *mailbox, const char
 
 /** 
  * \brief Determines if the given folder has messages.
- * \param mailbox The @ delimited string for user@context. If no context is found, uses 'default' for the context.
+ * \param mailbox The \@ delimited string for user\@context. If no context is found, uses 'default' for the context.
  * \param folder the folder to look in
  *
  * This function is used when the mailbox is stored in a filesystem back end.
@@ -15089,6 +15089,7 @@ static struct ast_vm_mailbox_snapshot *vm_mailbox_snapshot_destroy(struct ast_vm
  * \param msg_ids An array of message identifiers
  * \param num_msgs The number of identifiers in msg_ids
  * \param msg_nums [out] The message indexes corresponding to the given
+ * \param vmu
  * message IDs
  * \pre vms must have open_mailbox() called on it prior to this function.
  *
index 4145f1f..933d9e3 100644 (file)
@@ -22,7 +22,7 @@
  *
  * \brief ODBC CEL backend
  *
- * \author Tilghman Lesher <tlesher AT digium DOT com>
+ * \author Tilghman Lesher \verbatim <tlesher AT digium DOT com> \endverbatim
  * \ingroup cel_drivers
  */
 
index 444df77..6c4a822 100644 (file)
@@ -65,7 +65,9 @@ static const char name[] = "cel_sqlite3_custom";
 static sqlite3 *db = NULL;
 
 static char table[80];
-/*! XXX \bug Handling of this var is crash prone on reloads */
+/*!
+ * \bug Handling of this var is crash prone on reloads
+ */
 static char *columns;
 static struct ast_event_sub *event_sub = NULL;
 
index 30ce3d8..7ab6da2 100644 (file)
@@ -382,7 +382,7 @@ static struct ast_channel_tech agent_tech = {
  * unrefed once it is no longer needed.
  *
  * \param pvt Pointer to the LOCKED agent_pvt for which the owner is needed
- * \ref locked channel which owns the pvt at the time of completion. NULL if not available.
+ *     locked channel which owns the pvt at the time of completion. NULL if not available.
  */
 static struct ast_channel *agent_lock_owner(struct agent_pvt *pvt)
 {
index c3a5c58..13a5180 100644 (file)
@@ -24,7 +24,6 @@
  *
  * \par See also
  * \arg \ref Config_mgcp
- * \arg \ref res_pktccops
  *
  * \ingroup channel_drivers
  */
index a4a6da9..487264c 100644 (file)
@@ -40,7 +40,7 @@
  * \todo Transaction support
  *
  * ******** Wishlist: Improvements
- * - Support of SIP domains for devices, so that we match on username@domain in the From: header
+ * - Support of SIP domains for devices, so that we match on username\@domain in the From: header
  * - Connect registrations with a specific device on the incoming call. It's not done
  *   automatically in Asterisk
  *
@@ -729,7 +729,6 @@ static const struct sip_reasons {
        Default setttings are used as a channel setting and as a default when
        configuring devices
 */
-/*@{*/
 static char default_language[MAX_LANGUAGE];      /*!< Default language setting for new channels */
 static char default_callerid[AST_MAX_EXTENSION]; /*!< Default caller ID for sip messages */
 static char default_mwi_from[80];                /*!< Default caller ID for MWI updates */
@@ -749,7 +748,6 @@ static struct ast_codec_pref default_prefs;        /*!< Default codec prefs */
 static char default_zone[MAX_TONEZONE_COUNTRY];        /*!< Default tone zone for channels created from the SIP driver */
 static unsigned int default_transports;            /*!< Default Transports (enum sip_transport) that are acceptable */
 static unsigned int default_primary_transport;     /*!< Default primary Transport (enum sip_transport) for outbound connections to devices */
-/*@}*/
 
 static struct sip_settings sip_cfg;            /*!< SIP configuration data.
                                        \note in the future we could have multiple of these (per domain, per device group etc) */
index bcf2015..5dead0e 100644 (file)
@@ -113,14 +113,15 @@ enum {
 struct SpeexResamplerState_;
 typedef struct SpeexResamplerState_ SpeexResamplerState;
 
-/** Create a new resampler with integer input and output rates.
- * @param nb_channels Number of channels to be processed
- * @param in_rate Input sampling rate (integer number of Hz).
- * @param out_rate Output sampling rate (integer number of Hz).
- * @param quality Resampling quality between 0 and 10, where 0 has poor quality
- * and 10 has very high quality.
- * @return Newly created resampler state
- * @retval NULL Error: not enough memory
+/** \brief Create a new resampler with integer input and output rates.
+ * \param nb_channels Number of channels to be processed
+ * \param in_rate Input sampling rate (integer number of Hz).
+ * \param out_rate Output sampling rate (integer number of Hz).
+ * \param quality Resampling quality between 0 and 10, where 0 has poor quality
+ *     and 10 has very high quality.
+ * \param err
+ * \return Newly created resampler state
+ * \retval NULL Error: not enough memory
  */
 SpeexResamplerState *speex_resampler_init(spx_uint32_t nb_channels, 
                                           spx_uint32_t in_rate, 
index 29575f6..2f292d1 100644 (file)
@@ -38,7 +38,7 @@ PROJECT_NUMBER         =
 # If a relative path is entered, it will be relative to the location
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/api
+OUTPUT_DIRECTORY       = doc
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
 # 4096 sub-directories (in 2 levels) under the output directory of each output
@@ -47,7 +47,7 @@ OUTPUT_DIRECTORY       = doc/api
 # source files, where putting all generated files in the same directory would
 # otherwise cause performance problems for the file system.
 
-CREATE_SUBDIRS         = NO
+CREATE_SUBDIRS         = YES
 
 # The OUTPUT_LANGUAGE tag is used to specify the language in which all
 # documentation generated by doxygen is written. Doxygen will use this
@@ -301,7 +301,7 @@ SYMBOL_CACHE_SIZE      = 0
 
 EXTRACT_ALL            = YES
 
-# If the EXTRACT_PRIVATE tag is set to YES all private members of a class 
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
 # will be included in the documentation.
 
 EXTRACT_PRIVATE        = NO
@@ -548,12 +548,12 @@ WARN_IF_UNDOCUMENTED   = YES
 # parameters in a documented function, or documenting parameters that
 # don't exist or using markup commands wrongly.
 
-WARN_IF_DOC_ERROR      = YES
+WARN_IF_DOC_ERROR      = NO
 
-# This WARN_NO_PARAMDOC option can be abled to get warnings for 
-# functions that are documented, but have no documentation for their parameters 
-# or return value. If set to NO (the default) doxygen will only warn about 
-# wrong or incomplete parameter documentation, but not about the absence of 
+# This WARN_NO_PARAMDOC option can be abled to get warnings for
+# functions that are documented, but have no documentation for their parameters
+# or return value. If set to NO (the default) doxygen will only warn about
+# wrong or incomplete parameter documentation, but not about the absence of
 # documentation.
 
 WARN_NO_PARAMDOC       = NO
@@ -571,7 +571,7 @@ WARN_FORMAT            =
 # and error messages should be written. If left blank the output is written
 # to stderr.
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = doxygen.log
 
 #---------------------------------------------------------------------------
 # configuration options related to the input files
@@ -582,27 +582,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = ./ \
-                         agi \
-                         apps \
-                         bridges \
-                         cdr \
-                         channels \
-                         channels/sip \
-                         channels/misdn \
-                         codecs \
-                         formats \
-                         funcs \
-                         include \
-                         include/asterisk \
-                         include/asterisk/doxygen \
-                         main \
-                         main/stdtime \
-                         pbx \
-                         res \
-                         res/ael \
-                         res/ais \
-                         res/snmp
+INPUT                  =
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -627,13 +607,16 @@ FILE_PATTERNS          = *.c \
 # should be searched for input files as well. Possible values are YES and NO.
 # If left blank NO is used.
 
-RECURSIVE              = NO
+RECURSIVE              = yes
 
 # The EXCLUDE tag can be used to specify files and/or directories that should
 # excluded from the INPUT source files. This way you can easily exclude a
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-EXCLUDE                = 
+EXCLUDE                = doc/api \
+                         menuselect \
+                         res/pjproject \
+                         addons/ooh323c/src
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or
 # directories that are symbolic links (a Unix filesystem feature) are excluded
@@ -647,7 +630,9 @@ EXCLUDE_SYMLINKS       = YES
 # against the file with absolute path, so to exclude all test directories
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = *.o \
+                         *.o.d \
+                         .*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -677,7 +662,7 @@ EXAMPLE_PATTERNS       =
 # commands irrespective of the value of the RECURSIVE tag.
 # Possible values are YES and NO. If left blank NO is used.
 
-EXAMPLE_RECURSIVE      = NO
+EXAMPLE_RECURSIVE      = YES
 
 # The IMAGE_PATH tag can be used to specify one or more files or
 # directories that contain image that are included in the documentation (see
@@ -805,7 +790,7 @@ GENERATE_HTML          = YES
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be
 # put in front of it. If left blank `html' will be used as the default path.
 
-HTML_OUTPUT            = 
+HTML_OUTPUT            = api
 
 # The HTML_FILE_EXTENSION tag can be used to specify the file extension for
 # each generated HTML page (for example: .htm,.php,.asp). If it is left blank
@@ -817,7 +802,7 @@ HTML_FILE_EXTENSION    = .html
 # each generated HTML page. If it is left blank doxygen will generate a
 # standard header.
 
-HTML_HEADER            = contrib/asterisk-doxygen-header
+HTML_HEADER            =
 
 # The HTML_FOOTER tag can be used to specify a personal HTML footer for
 # each generated HTML page. If it is left blank doxygen will generate a
@@ -1244,7 +1229,7 @@ GENERATE_MAN           = NO
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be
 # put in front of it. If left blank `man' will be used as the default path.
 
-MAN_OUTPUT             = 
+MAN_OUTPUT             =
 
 # The MAN_EXTENSION tag determines the extension that is added to
 # the generated man pages (default is the subroutine's section .3)
@@ -1373,7 +1358,9 @@ SEARCH_INCLUDES        = YES
 # contain include files that are not input files but should be processed by
 # the preprocessor.
 
-INCLUDE_PATH           = include/ include/asterisk/
+INCLUDE_PATH           = ./ \
+                         include/ \
+                         include/asterisk/
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -1390,9 +1377,8 @@ INCLUDE_FILE_PATTERNS  =
 # undefined via #undef or recursively expanded use the := operator
 # instead of the = operator.
 
-PREDEFINED             = \
-            __GNUC__ \
-            __attribute__(x)=
+PREDEFINED             = __GNUC__ \
+                         __attribute__(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be expanded.
index 68a87e1..5adea86 100644 (file)
@@ -1,10 +1,14 @@
 The vast majority of the Asterisk project documentation has been moved to the
 project wiki:
     
-    http://wiki.asterisk.org/
+    https://wiki.asterisk.org/
 
 Asterisk release tarballs contain an export of the wiki in PDF and plain text
 form, which you can find in:
 
     doc/AST.pdf
     doc/AST.txt
+
+Asterisk uses the Doxygen documentation software.  Run "make progdocs" and open
+the resulting documentation index at doc/api/index.html in a webbrowser or copy
+the directory to a directory served by a webserver for remote access.
diff --git a/include/asterisk/doxygen/mantisworkflow.h b/include/asterisk/doxygen/mantisworkflow.h
deleted file mode 100644 (file)
index cb5f341..0000000
+++ /dev/null
@@ -1,206 +0,0 @@
-/*
- * Asterisk -- An open source telephony toolkit.
- *
- * Copyright (C) 1999 - 2009, Digium, Inc.
- *
- * See http://www.asterisk.org for more information about
- * the Asterisk project. Please do not directly contact
- * any of the maintainers of this project for assistance;
- * the project provides a web site, mailing lists and IRC
- * channels for your use.
- *
- * This program is free software, distributed under the terms of
- * the GNU General Public License Version 2. See the LICENSE file
- * at the top of the source tree.
- */
-
-/*!
- * \file
- */
-
-/*!
- * \page MantisWorkflow Workflow Guidelines for Asterisk Open Source Issue Tracker
- *
- * \AsteriskTrunkWarning
- *
- * <hr>
- * \section WorkflowDescription Description of the Issue Tracker Workflow
- * 
- * (This document is most beneficial for Asterisk bug marshals, however it is good
- * reading for anyone who may be filing issues or wondering how the Asterisk Open
- * Source project moves issues through from filing to completion.)
- * 
- * The workflow in the issue tracker should be handled in the following way:
- * 
- * -# A bug is reported and is automatically placed in the 'New' status.
- * -# The Bug Marshall team should go through bugs in the 'New' status to determine 
- *    whether the report is valid (not a duplicate, hasn't already been fixed, not 
- *    a Digium tech support issue, etc.).  Invalid reports should be set to 
- *    'Closed' with the appropriate resolution set. Categories and descriptions 
- *    should be corrected at this point.[Note1]\n
- *    Issues should also have enough information for a developer to either 
- *    reproduce the issue or determine where an issue exists (or both). If this is 
- *    not the case then the issue should be moved to 'Feedback' prior to moving 
- *    forward in the workflow.
- * -# The next step is to determine whether the report is about a bug or a 
- *    submission of a new feature:
- *       -# BUG: A bug should be moved into the status 'Acknowledged' if enough
- *          information has been provided by the reporter to either reproduce the
- *          issue or clearly see where an issue may lie. The bug may also be
- *          assigned to a developer for the creation of the initial patch, or
- *          review of the issue.\n
- *          Once a patch has been created for the issue and attached, the issue can
- *          then be moved to the 'Confirmed' status. At this point, initial code 
- *          review and discussion about the patch will take place. Once an adequate
- *          amount of support for the implementation of the patch is acquired, then
- *          the bug can be moved to the 'Ready for Testing' status for wider 
- *          testing by the community. After the testing phase is complete and it
- *          appears the issue is resolved, the patch can be committed by a 
- *          developer and closed.
- *       -# FEATURE: As new features should be filed with a patch, it can be 
- *          immediately moved to the 'confirmed' status, making it ready for basic
- *          formatting and code review. From there any changes to style or feel of
- *          the patch based on feedback from the community can be discussed, and
- *          changes to the patch made. It can then be moved forward to the 'Ready 
- *          for Testing' status. Once the feature has been merged, or a decision
- *          has been made that it will not be merged, the issue should be taken to 
- *          'Closed' with the appropriate resolution.[Note2]
- * -# If at any point in the workflow, an issue requires feedback from the original
- *    poster of the issue, the status should be changed to 'Feedback'.  Once the 
- *    required information has been provided, it should be placed back in the
- *    appropriate point of the workflow.
- * -# If at any point in the workflow, a developer or bug marshal would like to 
- *    take responsibility for doing the work that is necessary to progress an 
- *    issue, the status can be changed to 'Assigned'. At that point the developer
- *    assigned to the issue will be responsible for moving the issue to completion.
- * 
- * \section WorkflowSummary Workflow Summary
- * 
- * The following is a list of valid statuses and what they mean to the work flow.
- *
- * \subsection New New
- *    This issue is awaiting review by bug marshals.  Categorization and summaries
- *    should be fixed as appropriate.
- * 
- * \subsection Feedback
- *    This issue requires feedback from the poster of the issue before any
- *    additional progress in the workflow can be made. This may include providing
- *    additional debugging information, or a backtrace with DONT_OPTIMIZE enabled,
- *    for example. (See the doc/HOWTO_collect_debug_information.txt file in your
- *    Asterisk source.)
- * 
- * \subsection Acknowledged
- *    This is a submitted bug which has no patch associated with it, but appears
- *    to be a valid bug based on the description and provided debugging
- *    information.
- * 
- * \subsection Confirmed
- *    The patch associated with this issue requires initial formatting and code
- *    review, and may have some initial testing done. It is waiting for a 
- *    developer to confirm the patch will no longer need large changes made to it,
- *    and is ready for wider testing from the community. This stage is used for
- *    discussing the feel and style of a patch, in addition to the coding style
- *    utilized.
- * 
- * \subsection Ready For Testing
- *    This is an issue which has a patch that is waiting for testing feedback from
- *    the community after it has been deemed to no longer need larger changes.
- * 
- * \subsection Assigned
- *    A developer or bug marshal has taken responsibility for taking the necessary
- *    steps to move forward in the workflow.  Once the issue is ready to be
- *    reviewed and feedback provided, it should be placed back into the
- *    appropriate place of the workflow.
- * 
- * \subsection Resolved
- *    A resolution for this issue has been reached.  This issue should immediately
- *    be Closed.
- * 
- * \subsection Closed
- *    No further action is necessary for this issue.
- * 
- * \section SeverityLevels Severity Levels
- * 
- * Severity levels generally represent the number of users who are potentially
- * affected by the reported issue. 
- * 
- * \subsection Feature Feature
- *    This issue is a new feature and will only be committed to Asterisk trunk.
- *    Asterisk trunk is where future branches will be created and thus this
- *    feature will only be found in future branches of Asterisk and not merged
- *    into existing branches. (See Release Branch Commit Policy below.)
- * 
- * \subsection Trivial Trivial
- *    A trivial issue is something that either affects an insignificant number of
- *    Asterisk users, or is a minimally invasive change that does not affect
- *    functionality.
- * 
- * \subsection Text Text
- *    A text issue is typically something like a spelling fix, a clarifying of a
- *    debugging or verbose message, or changes to documentation.
- * 
- * \subsection Tweak Tweak
- *    A tweak to the code the has the potential to either make code clearer to
- *    read, or a change that could speed up processing in certain circumstances.
- *    These changes are typically only a couple of lines.
- * 
- * \subsection Minor Minor
- *    An issue that does not affect a large number of Asterisk users, but not an
- *    insignificant number. The number of lines of code and development effort to
- *    resolve this issue could be non-trivial.
- * 
- * \subsection Major Major
- *    As issue that affects the majority of Asterisk users. The number of lines of
- *    code and development effort required to resolve this issue could be
- *    non-trivial.
- * 
- * \subsection Crash Crash
- *    An issue marked as a Crash is something that would cause Asterisk to be
- *    unusable for a majority of Asterisk users and is an issue that causes a
- *    deadlock or crash of the Asterisk process.
- * 
- * \subsection Block Block
- *    A blocking issue is an issue that must be resolved before the next release
- *    of Asterisk as would affect a significant number of Asterisk users, or could
- *    be a highly visible regression. A severity of block should only be set by
- *    Asterisk bug marshals at their discretion.
- * 
- *        *** USERS SHOULD NOT FILE ISSUES WITH A SEVERITY OF BLOCK ***
- * 
- * \section PriorityLevels Priority Levels
- *
- * Currently, the following priority levels are listed on the issue tracker:
- * - None
- * - Low
- * - Normal
- * - High
- * - Urgent
- * - Immediate
- *
- * However, at this time they are not utilized and all new issue should have a priority of 'Normal'.
- *
- * \section Notes Notes
- * 
- * -# Using the "Need Triage" filter is useful for finding these issues quickly.
- * -# The issue tracker now has the ability to monitor the commits list, and if
- *    the commit message contains something like, "(Closes issue #9999)", the bug
- *    will be automatically closed.\n
- *    See http://www.asterisk.org/doxygen/trunk/CommitMessages.html for more
- *    information on commit messages.
- * 
- * \section ReleaseBranchCommitPolicy Release Branch Commit Policy
- * 
- * The code in the release branches should be changed as little as possible.  The 
- * only time the release branches will be changed is to fix a bug.  New features 
- * will never be included in the release branch unless a special exception is made
- * by the release branch maintainers.
- * 
- * Sometimes it is difficult to determine whether a patch is considered to fix a 
- * bug or if it is a new feature.  Patches that are considered code cleanup, or to 
- * improve performance, are NOT to be included in the release branches. Performance
- * issues will only be considered for the release branch if they are considered 
- * significant, and should be approved by the maintainers.
- * 
- * If there is ever a question about what should be included in the release branch,
- * the maintainers should be allowed to make the decision.
- */
index b617143..5b2612e 100644 (file)
@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 1999 - 2009, Digium, Inc.
+ * Copyright (C) 1999 - 2012, Digium, Inc.
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
@@ -17,9 +17,9 @@
 /*! 
  * \file
  *
- * This is the main header file used for generating miscellaneous developer
- * documentation using doxygen.  This also pulls in all of the documentation
- * that is in include/asterisk/doxygen/.
+ * This is the main header file used for generating miscellaneous documentation
+ * using Doxygen.  This also utilizes the documentation in 
+ * include/asterisk/doxygen/ header files.
  */
 
 /* 
 /*! 
  * \page AstDebug Debugging
  * \section debug Debugging
- * \verbinclude backtrace.txt
+ * \todo include backtrace txt that was removed
  */
 
 /*!
  * \page AstSpeech The Generic Speech Recognition API
  * \section debug The Generic Speech Recognition API
- * \verbinclude speechrec.txt
+ * \todo include missing speechrec txt
  */
 
 /*! 
  * \page DataStores Channel Data Stores
  * \section debug Channel Data Stores
- * \verbinclude datastores.txt
+ * \todo include missing datastores txt
  */
 
 /*! 
  * \section ami AMI - The manager Interface
  * \arg \link Config_ami Configuration file \endlink
  * \arg \ref manager.c
- * \verbinclude manager.txt
+ * \todo include missing manager txt
  */
 
 /*!
  * \section realtime ARA - a generic API to storage and retrieval
  * Implemented in \ref config.c 
  * Implemented in \ref pbx_realtime.c 
- * \verbinclude realtime.txt
- * \verbinclude extconfig.txt
+ * \todo include missing realtime txt
+ * \todo include missing extconfig txt
  */
 
 /*! 
  * \arg \ref cdr_drivers
  * \arg \ref Config_cdr CDR configuration files
  *
- * \verbinclude cdrdriver.txt
+ * \todo include missing cdrdriver txt
  */
 
 /*! 
 /*! 
  * \page AstVideo Video support in Asterisk
  * \section sectAstVideo Video support in Asterisk
- * \verbinclude video.txt
+ * \todo include missing video txt
  */
 
 /*! 
  * \par See also
  * \arg \ref cdrconf
  * \arg Implemented in \ref cdr_csv.c
- * \verbinclude cdr_csv.conf.sample
+ * \verbinclude cdr.conf.sample
  */
 
 /*! 
 
 /*! 
  * \page cdr_odbc Adaptive ODBC CDR driver configuration
- * \arg See also \ref cdrconf
- * \arg Implemented in \ref cdr_adaptive_odbc.c
+ * \li See also \ref cdrconf
  * \verbinclude cdr_adaptive_odbc.conf.sample
  * See also:
  * \arg http://www.unixodbc.org
  * \verbinclude cdr_pgsql.conf.sample
  */
 
-/*!
- * \page cdr_radius RADIUS CDR driver configuration
- * \arg See also \ref cdrconf
- * \arg Implemented in \ref cdr_radius.c
- * \verbinclude cdr_radius.conf.sample
- */
-
 /*! 
  * \page cdr_sqlite SQLite 2 CDR driver configuration
  * \arg See also \ref cdrconf
  */
 
 /*! 
+ * \page AstHTTP AMI over HTTP support
+ * The http.c file includes support for manager transactions over
+ * http.
+ * \section ami AMI - The manager Interface
+ * \arg \link Config_ami Configuration file \endlink
+ */
+
+/*! 
+ * \page res_config_sqlite SQLite Resource driver configuration
+ * \arg Implemented in \ref res_config_sqlite.c
+ * \arg Configuration file:
+ * \verbinclude res_config_sqlite.conf
+ * \arg SQL tables:
+ * \arg See also:
+ * http://www.sqlite.org
+ */
+
+/*
+ * Doxygen Groups
+ */
+
+/*! 
  * \addtogroup cdr_drivers Module: CDR Drivers
  * \section CDR_generic Asterisk CDR Drivers
  * \brief CDR drivers are loaded dynamically, each loaded CDR driver produce 
  * \arg \ref Config_cdr "CDR Configuration"
  */
 
-
 /*! 
  * \addtogroup channel_drivers Module: Asterisk Channel Drivers
  * \section channel_generic Asterisk Channel Drivers
  * \addtogroup rtp_engines Module: RTP Engines
  * \section rtp_engine_blah Asterisk RTP Engines
  */
-
-/*! 
- * \page AstHTTP AMI over HTTP support
- * The http.c file includes support for manager transactions over
- * http.
- * \section ami AMI - The manager Interface
- * \arg \link Config_ami Configuration file \endlink
- */
-
-/*! 
- * \page res_config_sqlite SQLite Resource driver configuration
- * \arg Implemented in \ref res_config_sqlite.c
- * \arg Configuration file:
- * \verbinclude res_config_sqlite.conf
- * \arg SQL tables:
- * \arg See also:
- * http://www.sqlite.org
- */
-
-
index 961b2c1..bdf786d 100644 (file)
@@ -265,7 +265,7 @@ void ast_format_sdp_generate(const struct ast_format *format, unsigned int paylo
  *
  * \param format to set
  * \param id format id to set on format
- * \param set_attributes, are there attributes to set on this format. 0 == false, 1 == True.
+ * \param set_attributes are there attributes to set on this format. 0 == false, 1 == True.
  * \param ... var list of attribute key value pairs, must end with AST_FORMAT_ATTR_END;
  *
  * \details Example usage.
index c20e2b8..fbaba4b 100644 (file)
@@ -821,7 +821,7 @@ int ast_context_add_include(const char *context, const char *include,
  * \brief Add a context include
  *
  * \param con context to add the include to
- * \param value include include to add
+ * \param value include value to add
  * \param registrar who registered the context
  *
  * Adds an include taking a struct ast_context as the first parameter
index 6442216..07abb6e 100644 (file)
@@ -234,7 +234,7 @@ int ast_xmpp_chatroom_join(struct ast_xmpp_client *client, const char *room, con
  *
  * \param client Pointer to the client
  * \param nickname Nickname to use
- * \param Address Address of the room
+ * \param address Address of the room
  * \param message Message itself
  *
  * \retval 0 on success
index ff37751..4e3d24e 100644 (file)
@@ -121,7 +121,8 @@ int daemon(int, int);  /* defined in libresolv of all places */
 #endif /* HAVE_CAP */
 #endif /* linux */
 
-#include "asterisk/paths.h"    /* we define here the variables so better agree on the prototype */
+/* we define here the variables so to better agree on the prototype */
+#include "asterisk/paths.h"
 #include "asterisk/network.h"
 #include "asterisk/cli.h"
 #include "asterisk/channel.h"
@@ -411,8 +412,6 @@ const char *ast_file_version_find(const char *file)
        return NULL;
 }
 
-
-
 struct thread_list_t {
        AST_RWLIST_ENTRY(thread_list_t) list;
        char *name;
index 7909484..3caa135 100644 (file)
@@ -20,7 +20,7 @@
  *
  * \brief Debugging routines for file descriptor leaks
  *
- * \author Tilghman Lesher <tlesher@digium.com>
+ * \author Tilghman Lesher \verbatim <tlesher@digium.com> \endverbatim
  */
 
 /*** MODULEINFO
index 0ca727d..d469362 100644 (file)
@@ -97,9 +97,11 @@ static int audiohook_set_internal_rate(struct ast_audiohook *audiohook, int rate
 }
 
 /*! \brief Initialize an audiohook structure
+ *
  * \param audiohook Audiohook structure
  * \param type
- * \param init, source, init_flags
+ * \param source, init_flags
+ *
  * \return Returns 0 on success, -1 on failure
  */
 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags init_flags)
index 2480c7d..9553321 100644 (file)
@@ -565,7 +565,7 @@ static enum ast_device_state cc_state_to_devstate_map[] = {
 };
 
 /*!
- * \intenral
+ * \internal
  * \brief lookup the ast_device_state mapped to cc_state
  *
  * \param state
index bb55544..4807dca 100644 (file)
@@ -1112,7 +1112,7 @@ struct mansession_session {
        int authenticated;      /*!< Authentication status */
        int readperm;           /*!< Authorization for reading */
        int writeperm;          /*!< Authorization for writing */
-       char inbuf[1025];       /*!< Buffer -  we use the extra byte to add a '\0' and simplify parsing */
+       char inbuf[1025];       /*!< Buffer -  we use the extra byte to add a '\\0' and simplify parsing */
        int inlen;              /*!< number of buffered bytes */
        struct ao2_container *whitefilters;     /*!< Manager event filters - white list */
        struct ao2_container *blackfilters;     /*!< Manager event filters - black list */
index d2b2aa1..6c1fbcd 100644 (file)
@@ -8799,7 +8799,7 @@ static const char * const months[] =
 };
 /*! /brief Build timing
  *
- * /param i, info
+ * /param i info
  * /param info_in
  *
  */
index c06b3ba..3c01d43 100644 (file)
@@ -2014,13 +2014,14 @@ static char *_xmldoc_build_field(struct ast_xml_node *node, const char *var, int
 }
 
 /*!
- *  \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
- *  \param type Type of element (application, function, ...).
- *  \param name Name of element (Dial, Echo, Playback, ...).
- *  \param var Name of field to return (synopsis, description, etc).
- *  \param raw Field only contains text, no other elements inside it.
- *  \retval NULL On error.
- *  \retval Field text content on success.
+ * \brief Get the content of a field (synopsis, description, etc) from an asterisk document tree
+ * \param type Type of element (application, function, ...).
+ * \param name Name of element (Dial, Echo, Playback, ...).
+ * \param var Name of field to return (synopsis, description, etc).
+ * \param module
+ * \param raw Field only contains text, no other elements inside it.
+ * \retval NULL On error.
+ * \retval Field text content on success.
  */
 static char *xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)
 {
index e2268fb..64b665b 100644 (file)
@@ -139,7 +139,7 @@ static void destroy_table(struct tables *table)
  *  \return -2 on query failure that resulted in disconnection
  *  \return 0 on success
  *
- *  \example see pgsql_exec for full example
+ *  \note see pgsql_exec for full example
  */
 static int _pgsql_exec(const char *database, const char *tablename, const char *sql, PGresult **result)
 {
index 4177586..e075360 100644 (file)
@@ -36,7 +36,7 @@
  *
  * \section conf_sec Configuration
  *
- * The main configuration file is res_config_sqlite.conf. It must be readable or
+ * The main configuration file is res_config_sqlite.conf.sample It must be readable or
  * res_config_sqlite will fail to start. It is suggested to use the sample file
  * in this package as a starting point. The file has only one section
  * named <code>general</code>. Here are the supported parameters :
index 57091bf..d065df6 100644 (file)
@@ -18,7 +18,7 @@
 
 /*!
  * \file
- * \author Tilghman Lesher <tlesher AT digium DOT com>
+ * \author Tilghman Lesher \verbatim <tlesher AT digium DOT com> \endverbatim
  *
  * \brief kqueue timing interface
  */
index 36573fa..604d8e3 100644 (file)
@@ -20,7 +20,7 @@
  * \file
  * \brief Gosub tests
  *
- * \author\verbatim Tilghman Lesher <tlesher AT digium DOT com> \endverbatim
+ * \author Tilghman Lesher \verbatim <tlesher AT digium DOT com> \endverbatim
  *
  * \ingroup tests
  */
index 58cfa0d..b2ad5b0 100644 (file)
  * the GNU General Public License Version 2. See the LICENSE file
  * at the top of the source tree.
  */
+
 /*! \file
  *
- *  \brief A program to read in the /tmp/refs file generated
+ * \brief A program to read in the /tmp/refs file generated
  *         by astobj2 code when the REF_DEBUG macro is defined.
  *         It will read in the file line by line, and
  *         sort the data out by object, and check to see
  *         this program reads in the /tmp/refs file and 
  *         generates no output. No news is good news.
  *  The contents of the /tmp/refs file looks like this:
+ * \verbatim
+ * 0x84fd718 -1   astobj2.c:926:cd_cb_debug (deref object via container destroy) [@1]
+ * 0x84fd718 =1   chan_sip.c:19760:build_user (allocate a user struct)
+ * 0x84fd718 +1   chan_sip.c:21558:reload_config (link user into users table) [@1]
+ * 0x84fd718 -1   chan_sip.c:2376:unref_user (Unref the result of build_user. Now, the table link is the only one left.) [@2]
+ * 0x84fd718 **call destructor** astobj2.c:926:cd_cb_debug (deref object via container destroy)
+ * \endverbatim
  *
-0x84fd718 -1   astobj2.c:926:cd_cb_debug (deref object via container destroy) [@1]
-0x84fd718 =1   chan_sip.c:19760:build_user (allocate a user struct)
-0x84fd718 +1   chan_sip.c:21558:reload_config (link user into users table) [@1]
-0x84fd718 -1   chan_sip.c:2376:unref_user (Unref the result of build_user. Now, the table link is the only one left.) [@2]
-0x84fd718 **call destructor** astobj2.c:926:cd_cb_debug (deref object via container destroy)
- *
- *
- *  \author Steve Murphy <murf@digium.com>
+ * \author Steve Murphy <murf@digium.com>
  */
 
 /*** MODULEINFO