Doxygen updates, formatting.

misdn stuff needs a lot of doxygenification

(Hello, Qwell :-) )


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

channels/DialTone.h

@@ -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, 

channels/gentone.c

@@ -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>

channels/iax2.h

@@ -10,6 +10,15 @@
  * 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

channels/misdn/chan_misdn_config.h

@@ -11,6 +11,12 @@
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN - Config
+ * \author Christian Richter <crich@beronet.com>
+ */
+
+
 
 
 #ifndef CHAN_MISDN_CONFIG_H

channels/misdn/ie.c

@@ -15,6 +15,11 @@
  * 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

channels/misdn/isdn_lib.c

@@ -11,6 +11,12 @@
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN
+ * \author Christian Richter <crich@beronet.com>
+ */
+
+
 
 #include <syslog.h>
 #include <mISDNuser/isdn_debug.h>

channels/misdn/isdn_lib.h

@@ -11,6 +11,13 @@
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * 
+ * Interface to mISDN
+ *
+ * \author Christian Richter <crich@beronet.com>
+ */
+
 #ifndef TE_LIB
 #define TE_LIB
 

channels/misdn/isdn_msg_parser.c

@@ -11,6 +11,12 @@
  * the GNU General Public License
  */
 
+/*! \file \brief
+ * Interface to mISDN - message parser
+ * \author Christian Richter <crich@beronet.com>
+ */
+
+
 
 #include "isdn_lib_intern.h"
 

channels/misdn/portinfo.c

@@ -1,3 +1,7 @@
+/*! \file \brief
+ * Interface to mISDN - ???
+ * \author Christian Richter <crich@beronet.com>
+ */
 
 
 #include "isdn_lib.h"

channels/ringtone.h

@@ -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, 

include/asterisk/doxyref.h

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

include/asterisk/manager.h

@@ -45,14 +45,18 @@
 
 \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 */
@@ -64,11 +68,12 @@
 #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 */
+/*! Add a custom hook to be called when an event is fired 
-/*! \param hook struct manager_custom_hook object to add
+ \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 */
+/*! Delete a custom hook to be called when an event is fired
-/*! \param hook struct manager_custom_hook object to delete
+    \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 */
+/*! \brief Register a manager command with the manager interface 
-/*! 	\param action Name of the requested Action:
+ 	\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 */
+/*! \brief Unregister a registred manager command 
-/*!	\param action Name of registred Action:
+	\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 */
+/*! \brief External routines may send asterisk manager events this way 
-/*! 	\param category	Event category, matches manager authorization
+ *  	\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 */

include/asterisk/term.h

@@ -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);
 

include/asterisk/transcap.h

@@ -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

include/asterisk/translate.h

@@ -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)
 
 /*!

include/asterisk/udptl.h

@@ -15,6 +15,14 @@
  * 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;

include/asterisk/ulaw.h

@@ -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,

include/asterisk/zapata.h

@@ -19,10 +19,7 @@
 
 /*! \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)

include/jitterbuf.h

@@ -13,6 +13,13 @@
  * 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_CONTROL,  /*!< 0            */
-	JB_TYPE_VOICE,    /* 1            */
+	JB_TYPE_VOICE,    /*!< 1            */
-	JB_TYPE_VIDEO,    /* 2 - reserved */
+	JB_TYPE_VIDEO,    /*!< 2 - reserved */
-	JB_TYPE_SILENCE   /* 3            */
+	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 */
+/*! \brief reset jitterbuf
-/* NOTE:  The jitterbuffer should be empty before you call this, otherwise
+ * \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, ...);
+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);
+void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg);
 
 #ifdef __cplusplus
 }

main/cygload.c

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