kenmirrors/asterisk
1
0
Fork 0
mirror of https://github.com/asterisk/asterisk.git synced 2025-09-29 18:19:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Doxygen Updates Janitor Work

Browse Source 
* 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
This commit is contained in:
Andrew Latham
2012-09-22 20:43:30 +00:00
parent ca8aeeef1b
commit fd98835f1f
30 changed files with 143 additions and 361 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
include/asterisk/doxygen/mantisworkflow.h
View File

@@ -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.
*/

79
include/asterisk/doxyref.h
View 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.
*/
/*
@@ -133,19 +133,19 @@
/*!
* \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
*/
/*!
@@ -153,7 +153,7 @@
* \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
*/
/*!
@@ -161,8 +161,8 @@
* \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
*/
/*!
@@ -191,7 +191,7 @@
* \arg \ref cdr_drivers
* \arg \ref Config_cdr CDR configuration files
*
* \verbinclude cdrdriver.txt
* \todo include missing cdrdriver txt
*/
/*!
@@ -207,7 +207,7 @@
/*!
* \page AstVideo Video support in Asterisk
* \section sectAstVideo Video support in Asterisk
* \verbinclude video.txt
* \todo include missing video txt
*/
/*!
@@ -486,7 +486,7 @@
* \par See also
* \arg \ref cdrconf
* \arg Implemented in \ref cdr_csv.c
* \verbinclude cdr_csv.conf.sample
* \verbinclude cdr.conf.sample
*/
/*!
@@ -517,8 +517,7 @@
/*!
* \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
@@ -533,13 +532,6 @@
* \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
@@ -648,6 +640,28 @@
* repository on svn.digium.com
*/
/*!
* \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
@@ -657,7 +671,6 @@
* \arg \ref Config_cdr "CDR Configuration"
*/
/*!
* \addtogroup channel_drivers Module: Asterisk Channel Drivers
* \section channel_generic Asterisk Channel Drivers
@@ -705,23 +718,3 @@
* \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
*/

2
include/asterisk/format.h
View 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.

2
include/asterisk/pbx.h
View 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

2
include/asterisk/xmpp.h
View 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