Doxygen updates, formatting.
authorOlle Johansson <oej@edvina.net>
Tue, 11 Dec 2007 22:20:22 +0000 (22:20 +0000)
committerOlle Johansson <oej@edvina.net>
Tue, 11 Dec 2007 22:20:22 +0000 (22:20 +0000)
misdn stuff needs a lot of doxygenification

(Hello, Qwell :-) )

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

20 files changed:
channels/DialTone.h
channels/gentone.c
channels/iax2.h
channels/misdn/chan_misdn_config.h
channels/misdn/ie.c
channels/misdn/isdn_lib.c
channels/misdn/isdn_lib.h
channels/misdn/isdn_msg_parser.c
channels/misdn/portinfo.c
channels/ringtone.h
include/asterisk/doxyref.h
include/asterisk/manager.h
include/asterisk/term.h
include/asterisk/transcap.h
include/asterisk/translate.h
include/asterisk/udptl.h
include/asterisk/ulaw.h
include/asterisk/zapata.h
include/jitterbuf.h
main/cygload.c

index 098ed44..e71ba0c 100644 (file)
@@ -9,6 +9,11 @@
   *
   */
 
+/*! \file
+ * \brief
+ * 8-bit raw data
+ */
+
 static unsigned char DialTone[] = {
 0xff, 0xab, 0x9d, 0x96, 0x91, 0x90, 0x91, 0x96, 0x9c, 0xaa, 
 0xd9, 0x2f, 0x1f, 0x19, 0x15, 0x14, 0x15, 0x19, 0x1f, 0x2c, 
index 29bd88e..fc97e38 100644 (file)
@@ -1,6 +1,11 @@
 /* Generate a header file for a particular 
    single or double frequency */
 
+/*! \file
+ * \brief
+ * Generate a header file for a particular single or double frequency 
+ */
+
 #include <stdio.h>
 #include <math.h>
 #include <string.h>
index 9974881..b3947ff 100644 (file)
  * This program is free software, distributed under the terms of
  * the GNU General Public License
  */
+
+/*! \file
+ * \brief
+ *
+ * Implementation of Inter-Asterisk eXchange, version 2
+ * \ref iax2-parser.c
+ * \ref iax2-parser.h
+ * \ref chan_iax2.c
+ */
  
 #ifndef _IAX2_H
 #define _IAX2_H
index f9475bd..8c27f4f 100644 (file)
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN - Config
+ * \author Christian Richter <crich@beronet.com>
+ */
+
+
 
 
 #ifndef CHAN_MISDN_CONFIG_H
index 9c783cd..817e3d8 100644 (file)
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN
+ * \author Christian Richter <crich@beronet.com>
+ */
+
 /*
   the pointer of enc_ie_* always points to the IE itself
   if qi is not NULL (TE-mode), offset is set
index 888887d..67ecb47 100644 (file)
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN
+ * \author Christian Richter <crich@beronet.com>
+ */
+
+
 
 #include <syslog.h>
 #include <mISDNuser/isdn_debug.h>
index 5dc374c..731d497 100644 (file)
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * 
+ * Interface to mISDN
+ *
+ * \author Christian Richter <crich@beronet.com>
+ */
+
 #ifndef TE_LIB
 #define TE_LIB
 
index 720f43d..ebaf6a9 100644 (file)
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN - message parser
+ * \author Christian Richter <crich@beronet.com>
+ */
+
+
 
 #include "isdn_lib_intern.h"
 
index bcb9f03..8223164 100644 (file)
@@ -1,3 +1,7 @@
+/*! \file \brief
+ * Interface to mISDN - ???
+ * \author Christian Richter <crich@beronet.com>
+ */
 
 
 #include "isdn_lib.h"
index 559c42a..f4eac96 100644 (file)
@@ -1,5 +1,9 @@
 /* ringtone.h: Generated from frequencies 440 and 480 
    by gentone.  200 samples  */
+/*! \file
+    \brief
+ Generated from frequencies 440 and 480 by gentone.  200 samples 
+*/
 static short ringtone[200] = {
            0, 11581, 21659, 28927, 32445, 31764, 26981, 18727, 
         8084, -3559, -14693, -23875, -29927, -32083, -30088, -24228, 
index 6e4b0e9..6fbe462 100644 (file)
@@ -16,7 +16,8 @@
  * at the top of the source tree.
  */
 
-/*! \file doxyref.h This file generates Doxygen pages from files in the /doc
+/*! \file 
+ * \brief This file generates Doxygen pages from files in the /doc
  directory of the Asterisk source code tree 
  */
 
index a57e890..8e63acf 100644 (file)
 
 \endverbatim
 
- ** Please try to re-use existing headers to simplify manager message parsing in clients.
+ \note Please try to \b re-use \b existing \b headers to simplify manager message parsing in clients.
     Don't re-use an existing header with a new meaning, please.
     You can find a reference of standard headers in doc/manager.txt
+
+- \ref manager.c Main manager code file
  */
 
 #define AMI_VERSION                     "1.1"
 #define DEFAULT_MANAGER_PORT 5038      /* Default port for Asterisk management via TCP */
 
+/*! \name Manager event classes */
+/*@{ */
 #define EVENT_FLAG_SYSTEM              (1 << 0) /* System events such as module load/unload */
 #define EVENT_FLAG_CALL                        (1 << 1) /* Call event, such as state change, etc */
 #define EVENT_FLAG_LOG                 (1 << 2) /* Log events */
 #define EVENT_FLAG_DTMF                (1 << 8) /* Ability to read DTMF events */
 #define EVENT_FLAG_REPORTING           (1 << 9) /* Reporting events such as rtcp sent */
 #define EVENT_FLAG_CDR                 (1 << 10) /* CDR events */
+/*@} */
 
-/* Export manager structures */
+/*! \brief Export manager structures */
 #define AST_MAX_MANHEADERS 128
 
-/* Manager Helper Function */
+/*! \brief Manager Helper Function */
 typedef int (*manager_hook_t)(int, const char *, char *); 
 
 
@@ -87,13 +92,13 @@ int check_manager_enabled(void);
 /*! \brief Check if AMI/HTTP is enabled */
 int check_webmanager_enabled(void);
 
-/*! Add a custom hook to be called when an event is fired */
-/*! \param hook struct manager_custom_hook object to add
+/*! Add a custom hook to be called when an event is fired 
+ \param hook struct manager_custom_hook object to add
 */
 void ast_manager_register_hook(struct manager_custom_hook *hook);
 
-/*! Delete a custom hook to be called when an event is fired */
-/*! \param hook struct manager_custom_hook object to delete
+/*! Delete a custom hook to be called when an event is fired
+    \param hook struct manager_custom_hook object to delete
 */
 void ast_manager_unregister_hook(struct manager_custom_hook *hook);
 
@@ -119,13 +124,13 @@ struct manager_action {
        AST_RWLIST_ENTRY(manager_action) list;
 };
 
-/* External routines may register/unregister manager callbacks this way */
+/*! \brief External routines may register/unregister manager callbacks this way 
+ * \note  Use ast_manager_register2() to register with help text for new manager commands */
 #define ast_manager_register(a, b, c, d) ast_manager_register2(a, b, c, d, NULL)
 
-/* Use ast_manager_register2 to register with help text for new manager commands */
 
-/*! Register a manager command with the manager interface */
-/*!    \param action Name of the requested Action:
+/*! \brief Register a manager command with the manager interface 
+       \param action Name of the requested Action:
        \param authority Required authority for this command
        \param func Function to call for this command
        \param synopsis Help text (one line, up to 30 chars) for CLI manager show commands
@@ -138,8 +143,8 @@ int ast_manager_register2(
        const char *synopsis,
        const char *description);
 
-/*! Unregister a registred manager command */
-/*!    \param action Name of registred Action:
+/*! \brief Unregister a registred manager command 
+       \param action Name of registred Action:
 */
 int ast_manager_unregister( char *action );
 
@@ -161,8 +166,8 @@ int astman_verify_session_readpermissions(unsigned long ident, int perm);
  */
 int astman_verify_session_writepermissions(unsigned long ident, int perm);
 
-/*! External routines may send asterisk manager events this way */
-/*!    \param category Event category, matches manager authorization
+/*! \brief External routines may send asterisk manager events this way 
+ *     \param category Event category, matches manager authorization
        \param event    Event name
        \param contents Contents of event
 */
@@ -176,22 +181,30 @@ int __attribute__ ((format(printf, 6, 7))) __manager_event(int category, const c
                                                           const char *file, int line, const char *func,
                                                           const char *contents, ...);
 
-/*! Get header from mananger transaction */
+/*! \brief Get header from mananger transaction */
 const char *astman_get_header(const struct message *m, char *var);
 
-/*! Get a linked list of the Variable: headers */
+/*! \brief Get a linked list of the Variable: headers */
 struct ast_variable *astman_get_variables(const struct message *m);
 
-/*! Send error in manager transaction */
+/*! \brief Send error in manager transaction */
 void astman_send_error(struct mansession *s, const struct message *m, char *error);
+
+/*! \brief Send response in manager transaction */
 void astman_send_response(struct mansession *s, const struct message *m, char *resp, char *msg);
+
+/*! \brief Send ack in manager transaction */
 void astman_send_ack(struct mansession *s, const struct message *m, char *msg);
+
+/*! \brief Send ack in manager list transaction */
 void astman_send_listack(struct mansession *s, const struct message *m, char *msg, char *listflag);
 
 void __attribute__ ((format (printf, 2, 3))) astman_append(struct mansession *s, const char *fmt, ...);
 
-/*! Called by Asterisk initialization */
+/*! \brief Called by Asterisk initialization */
 int init_manager(void);
+
+/*! \brief Called by Asterisk module functions and the CLI command */
 int reload_manager(void);
 
 #endif /* _ASTERISK_MANAGER_H */
index 3b454ce..3277f00 100644 (file)
@@ -28,6 +28,10 @@ extern "C" {
 #endif
 
 #define ESC 0x1b
+
+/*! \name Terminal Attributes 
+*/
+/*@{ */
 #define ATTR_RESET     0
 #define ATTR_BRIGHT    1
 #define ATTR_DIM       2
@@ -35,7 +39,11 @@ extern "C" {
 #define ATTR_BLINK     5
 #define ATTR_REVER     7
 #define ATTR_HIDDEN    8
+/*@} */
 
+/*! \name Terminal Colors
+*/
+/*@{ */
 #define COLOR_BLACK    30
 #define COLOR_GRAY     (30 | 128)
 #define COLOR_RED      31
@@ -52,6 +60,7 @@ extern "C" {
 #define COLOR_BRCYAN    (36 | 128)
 #define COLOR_WHITE     37
 #define COLOR_BRWHITE   (37 | 128)
+/*@} */
 
 char *term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout);
 
index 5da8329..1eca28d 100644 (file)
@@ -28,6 +28,9 @@
  * that utilize these fields.
  */
 
+/*! \name AstTranscode General Asterisk channel transcoding definitions.
+*/
+/*@{ */
 #define AST_TRANS_CAP_SPEECH                           0x0
 #define AST_TRANS_CAP_DIGITAL                          0x08
 #define AST_TRANS_CAP_RESTRICTED_DIGITAL               0x09
@@ -35,6 +38,7 @@
 #define AST_TRANS_CAP_7K_AUDIO                         0x11    /* Depriciated ITU Q.931 (05/1998)*/
 #define AST_TRANS_CAP_DIGITAL_W_TONES                  0x11
 #define AST_TRANS_CAP_VIDEO                            0x18
+/*@} */
 
 #define IS_DIGITAL(cap)\
        (cap) & AST_TRANS_CAP_DIGITAL ? 1 : 0
index 75023f0..2db3019 100644 (file)
@@ -18,6 +18,7 @@
 
 /*! \file
  * \brief Support for translation of data formats.
+ * \ref translate.c
  */
 
 #ifndef _ASTERISK_TRANSLATE_H
@@ -40,7 +41,9 @@ extern "C" {
 struct ast_trans_pvt;  /* declared below */
 
 /*! \brief
- * Descriptor of a translator. Name, callbacks, and various options
+ * Descriptor of a translator. 
+ *
+ * Name, callbacks, and various options
  * related to run-time operation (size of buffers, auxiliary
  * descriptors, etc).
  *
@@ -116,7 +119,7 @@ struct ast_translator {
 /*! \brief
  * Default structure for translators, with the basic fields and buffers,
  * all allocated as part of the same chunk of memory. The buffer is
- * preceded by AST_FRIENDLY_OFFSET bytes in front of the user portion.
+ * preceded by \ref AST_FRIENDLY_OFFSET bytes in front of the user portion.
  * 'buf' points right after this space.
  *
  * *_framein() routines operate in two ways:
@@ -158,6 +161,8 @@ struct ast_trans_pvt;
  * \return 0 on success, -1 on failure
  */
 int __ast_register_translator(struct ast_translator *t, struct ast_module *module);
+
+/*! \brief See \ref __ast_register_translator() */
 #define ast_register_translator(t) __ast_register_translator(t, ast_module_info->self)
 
 /*!
index 090cc5b..74fcf35 100644 (file)
  * this code.
  */
 
+/*! \file
+ * \brief UDPTL support for T.38
+ * \author Steve Underwood <steveu@coppice.org>
+ * \ref udptl.c
+ * \todo add doxygen documentation to this file!
+ */
+
+
 #ifndef _ASTERISK_UDPTL_H
 #define _ASTERISK_UDPTL_H
 
@@ -24,8 +32,8 @@
 #include "asterisk/sched.h"
 #include "asterisk/channel.h"
 
-enum
-{
+
+enum {
     UDPTL_ERROR_CORRECTION_NONE,
     UDPTL_ERROR_CORRECTION_FEC,
     UDPTL_ERROR_CORRECTION_REDUNDANCY
@@ -36,9 +44,9 @@ extern "C" {
 #endif
 
 struct ast_udptl_protocol {
-       /* Get UDPTL struct, or NULL if unwilling to transfer */
+       /*! \brief Get UDPTL struct, or NULL if unwilling to transfer */
        struct ast_udptl *(*get_udptl_info)(struct ast_channel *chan);
-       /* Set UDPTL peer */
+       /*! \brief Set UDPTL peer */
        int (* const set_udptl_peer)(struct ast_channel *chan, struct ast_udptl *peer);
        const char * const type;
        AST_RWLIST_ENTRY(ast_udptl_protocol) list;
index 1ac079d..0f3eae5 100644 (file)
@@ -24,7 +24,6 @@
 #define _ASTERISK_ULAW_H
 
 
-/*! Init the ulaw conversion stuff */
 /*!
  * To init the ulaw to slinear conversion stuff, this needs to be run.
  */
@@ -35,9 +34,7 @@ void ast_ulaw_init(void);
 #define AST_ULAW_TAB_SIZE  (32768 / AST_ULAW_STEP + 1)
 #define AST_ULAW_SIGN_BIT  0x80
 
-/*! converts signed linear to mulaw */
-/*!
-  */
+/*! \brief converts signed linear to mulaw */
 #ifndef G711_NEW_ALGORITHM
 extern unsigned char __ast_lin2mu[16384];
 #else
@@ -57,7 +54,7 @@ extern short __ast_mulaw[256];
        __ast_lin2mu[((mag) + AST_ULAW_STEP / 2) >> AST_ULAW_BIT_LOSS]
 
 
-/*! convert signed linear sample to sign-magnitude pair for u-Law */
+/*! \brief convert signed linear sample to sign-magnitude pair for u-Law */
 static inline void ast_ulaw_get_sign_mag(short sample, unsigned *sign, unsigned *mag)
 {
        /* It may look illogical to retrive the sign this way in both cases,
index 8d7eff7..50df73a 100644 (file)
 
 /*! \file
  * \brief Stub to find zaptel headers
- */
-
-
-/*
+*
  * Stub to find the zaptel headers. The configure script will
  * define HAVE_ZAPTEL_VERSION according to what it has found.
  * Applications should include "zapata.h" and not (directly)
index d2e5b5a..2a6045f 100644 (file)
  * Copyright on this file is disclaimed to Digium for inclusion in Asterisk
  */
 
+/*! \file
+ * \brief 
+ * jitterbuf: an application-independent jitterbuffer
+ * \ref jitterbuf.c
+ */
+
+
 #ifndef _JITTERBUF_H_
 #define _JITTERBUF_H_
 
@@ -20,7 +27,8 @@
 extern "C" {
 #endif
 
-/* configuration constants */
+/*! \name configuration constants */
+/*@{ */
        /*! Number of historical timestamps to use in calculating jitter and drift */
 #define JB_HISTORY_SZ          500     
        /*! what percentage of timestamps should we drop from the history when we examine it;
@@ -34,6 +42,7 @@ extern "C" {
 #define JB_TARGET_EXTRA 40
        /*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
 #define JB_ADJUST_DELAY 40
+/*@} */
 
 enum jb_return_code {
        /* return codes */
@@ -47,10 +56,10 @@ enum jb_return_code {
 
 enum jb_frame_type {
        /* frame types */
-       JB_TYPE_CONTROL,  /* 0            */
-       JB_TYPE_VOICE,    /* 1            */
-       JB_TYPE_VIDEO,    /* 2 - reserved */
-       JB_TYPE_SILENCE   /* 3            */
+       JB_TYPE_CONTROL,  /*!< 0            */
+       JB_TYPE_VOICE,    /*!< 1            */
+       JB_TYPE_VIDEO,    /*!< 2 - reserved */
+       JB_TYPE_SILENCE   /*!< 3            */
 };
 
 typedef struct jb_conf {
@@ -111,18 +120,20 @@ typedef struct jitterbuf {
 } jitterbuf;
 
 
-/* new jitterbuf */
+/*! \brief new jitterbuf */
 jitterbuf *            jb_new(void);
 
-/* destroy jitterbuf */
+/*! \brief destroy jitterbuf */
 void                   jb_destroy(jitterbuf *jb);
 
-/* reset jitterbuf */
-/* NOTE:  The jitterbuffer should be empty before you call this, otherwise
+/*! \brief reset jitterbuf
+ * \note The jitterbuffer should be empty before you call this, otherwise
  * you will leak queued frames, and some internal structures */
 void                   jb_reset(jitterbuf *jb);
 
-/* queue a frame data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) 
+/*!\brief  queue a frame 
+ * 
+ * data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) 
  * now=now (in receiver's time) return value is one of 
  * JB_OK: Frame added. Last call to jb_next() still valid
  * JB_DROP: Drop this frame immediately
@@ -130,7 +141,7 @@ void                        jb_reset(jitterbuf *jb);
  */
 enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts, long now);
 
-/* get a frame for time now (receiver's time)  return value is one of
+/*! \brief get a frame for time now (receiver's time)  return value is one of
  * JB_OK:  You've got frame!
  * JB_DROP: Here's an audio frame you should just drop.  Ask me again for this time..
  * JB_NOFRAME: There's no frame scheduled for this time.
@@ -139,21 +150,21 @@ enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type t
  */
 enum jb_return_code jb_get(jitterbuf *jb, jb_frame *frame, long now, long interpl);
 
-/* unconditionally get frames from jitterbuf until empty */
+/*! \brief unconditionally get frames from jitterbuf until empty */
 enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout);
 
-/* when is the next frame due out, in receiver's time (0=EMPTY) 
+/*! \brief when is the next frame due out, in receiver's time (0=EMPTY) 
  * This value may change as frames are added (esp non-audio frames) */
-long                   jb_next(jitterbuf *jb);
+long   jb_next(jitterbuf *jb);
 
-/*! get jitterbuf info: only "statistics" may be valid */
+/*! \brief get jitterbuf info: only "statistics" may be valid */
 enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats);
 
-/*! set jitterbuf conf */
+/*! \brief set jitterbuf conf */
 enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf);
 
-typedef                void (*jb_output_function_t)(const char *fmt, ...);
-void                   jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg);
+typedef        void (*jb_output_function_t)(const char *fmt, ...);
+void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg);
 
 #ifdef __cplusplus
 }
index 5945af4..fd8f3d5 100644 (file)
@@ -1,7 +1,25 @@
 /*
- * Loader for asterisk under windows.
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 1999 - 2005, 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
+ * \brief 
+ * Loader for Asterisk under Cygwin/windows.
  * Open the dll, locate main, run.
  */
+
 #include <unistd.h>
 #include <dlfcn.h>
 #include <stdio.h>
@@ -16,6 +34,6 @@ int main(int argc, char *argv[])
                ast_main = (main_f)dlsym(handle, "main");
        if (ast_main)
                return ast_main(argc, argv);
-       fprintf(stderr, "could not load asterisk, %s\n", dlerror());
+       fprintf(stderr, "could not load Asterisk, %s\n", dlerror());
        return 1;       /* there was an error */
 }