From c76f72493a8b76a798d5d867f6b096fa41b78c25 Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Tue, 11 Dec 2007 22:20:22 +0000 Subject: Doxygen updates, formatting. 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 --- include/asterisk/doxyref.h | 3 ++- include/asterisk/manager.h | 51 +++++++++++++++++++++++++++----------------- include/asterisk/term.h | 9 ++++++++ include/asterisk/transcap.h | 4 ++++ include/asterisk/translate.h | 9 ++++++-- include/asterisk/udptl.h | 16 ++++++++++---- include/asterisk/ulaw.h | 7 ++---- include/asterisk/zapata.h | 5 +---- include/jitterbuf.h | 47 ++++++++++++++++++++++++---------------- 9 files changed, 98 insertions(+), 53 deletions(-) (limited to 'include') diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 6e4b0e99b..6fbe462ec 100644 --- a/include/asterisk/doxyref.h +++ b/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 */ diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h index a57e890fd..8e63acfee 100644 --- a/include/asterisk/manager.h +++ b/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 */ -/*! \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 */ diff --git a/include/asterisk/term.h b/include/asterisk/term.h index 3b454ce2c..3277f0042 100644 --- a/include/asterisk/term.h +++ b/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); diff --git a/include/asterisk/transcap.h b/include/asterisk/transcap.h index 5da8329dc..1eca28d6d 100644 --- a/include/asterisk/transcap.h +++ b/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 diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h index 75023f0ad..2db3019c1 100644 --- a/include/asterisk/translate.h +++ b/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) /*! diff --git a/include/asterisk/udptl.h b/include/asterisk/udptl.h index 090cc5b07..74fcf357d 100644 --- a/include/asterisk/udptl.h +++ b/include/asterisk/udptl.h @@ -15,6 +15,14 @@ * this code. */ +/*! \file + * \brief UDPTL support for T.38 + * \author Steve Underwood + * \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; diff --git a/include/asterisk/ulaw.h b/include/asterisk/ulaw.h index 1ac079d54..0f3eae58b 100644 --- a/include/asterisk/ulaw.h +++ b/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, diff --git a/include/asterisk/zapata.h b/include/asterisk/zapata.h index 8d7eff74f..50df73a58 100644 --- a/include/asterisk/zapata.h +++ b/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) diff --git a/include/jitterbuf.h b/include/jitterbuf.h index d2e5b5ac0..2a6045f05 100644 --- a/include/jitterbuf.h +++ b/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_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 } -- cgit v1.2.3