(closes issue #10271)

Reported by: snuffy
Patches:
      doxygen-updates.diff uploaded by snuffy (license 35)

Another big batch of doxygen documentation updates


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

4 files changed, 51 insertions, 50 deletions

diff --git a/include/asterisk.h b/include/asterisk.h
index 6e20c16a9..7dd5897d3 100644
--- a/include/asterisk.h
+++ b/include/asterisk.h
@@ -105,9 +105,10 @@ struct ast_module;
  * \note Modules are reloaded using their reload() functions, not unloading
  * them and loading them again.
  * 
- * \return Zero if the specified module was not found, 1 if the module was
- * found but cannot be reloaded, -1 if a reload operation is already in
- * progress, and 2 if the specfied module was found and reloaded.
+ * \return 0 if the specified module was not found.
+ * \retval 1 if the module was found but cannot be reloaded.
+ * \retval -1 if a reload operation is already in progress.
+ * \retval 2 if the specfied module was found and reloaded.
  */
 int ast_module_reload(const char *name);
 
@@ -115,7 +116,8 @@ int ast_module_reload(const char *name);
  * \brief Register a function to be executed before Asterisk exits.
  * \param func The callback function to use.
  *
- * \return Zero on success, -1 on error.
+ * \retval 0 on success.
+ * \retval -1 on error.
  */
 int ast_register_atexit(void (*func)(void));
 
diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h
index 3d0511804..bf538c6d8 100644
--- a/include/asterisk/doxyref.h
+++ b/include/asterisk/doxyref.h
@@ -551,4 +551,3 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *  \arg \link Config_ami Configuration file \endlink
  *  \verbinclude ajam.txt
  */
-
diff --git a/include/asterisk/file.h b/include/asterisk/file.h
index 008759713..22a887c66 100644
--- a/include/asterisk/file.h
+++ b/include/asterisk/file.h
@@ -107,7 +107,7 @@ struct ast_format {
 	 * When allocating a buffer, remember to leave AST_FRIENDLY_OFFSET
 	 * spare bytes at the bginning.
 	 */
-	int buf_size;			/* size of frame buffer, if any, aligned to 8 bytes. */
+	int buf_size;			/*!< size of frame buffer, if any, aligned to 8 bytes. */
 	int desc_size;			/*!< size of private descriptor, if any */
 
 	struct ast_module *module;
@@ -134,9 +134,9 @@ struct ast_filestream {
 	int lasttimeout;
 	struct ast_channel *owner;
 	FILE *f;
-	struct ast_frame fr;	/* frame produced by read, typically */
-	char *buf;		/* buffer pointed to by ast_frame; */
-	void *private;	/* pointer to private buffer */
+	struct ast_frame fr;	/*!< frame produced by read, typically */
+	char *buf;		/*!< buffer pointed to by ast_frame; */
+	void *private;	/*!< pointer to private buffer */
 };
 
 #define SEEK_FORCECUR	10
diff --git a/include/jitterbuf.h b/include/jitterbuf.h
index d2635f3f0..d2e5b5ac0 100644
--- a/include/jitterbuf.h
+++ b/include/jitterbuf.h
@@ -21,18 +21,18 @@ extern "C" {
 #endif
 
 /* configuration constants */
-	/* Number of historical timestamps to use in calculating jitter and drift */
+	/*! 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;
+	/*! what percentage of timestamps should we drop from the history when we examine it;
 	 * this might eventually be something made configurable */
 #define JB_HISTORY_DROPPCT	3
-	/* the maximum droppct we can handle (say it was configurable). */
+	/*! the maximum droppct we can handle (say it was configurable). */
 #define JB_HISTORY_DROPPCT_MAX	4
-	/* the size of the buffer we use to keep the top and botton timestamps for dropping */
+	/*! the size of the buffer we use to keep the top and botton timestamps for dropping */
 #define JB_HISTORY_MAXBUF_SZ	JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100 
-	/* amount of additional jitterbuffer adjustment  */
+	/*! amount of additional jitterbuffer adjustment  */
 #define JB_TARGET_EXTRA 40
-	/* ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
+	/*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
 #define JB_ADJUST_DELAY 40
 
 enum jb_return_code {
@@ -55,36 +55,36 @@ enum jb_frame_type {
 
 typedef struct jb_conf {
 	/* settings */
-	long max_jitterbuf;	/* defines a hard clamp to use in setting the jitter buffer delay */
- 	long resync_threshold;  /* the jb will resync when delay increases to (2 * jitter) + this param */
-	long max_contig_interp; /* the max interp frames to return in a row */
-	long target_extra ;      /* amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
+	long max_jitterbuf;	/*!< defines a hard clamp to use in setting the jitter buffer delay */
+ 	long resync_threshold;  /*!< the jb will resync when delay increases to (2 * jitter) + this param */
+	long max_contig_interp; /*!< the max interp frames to return in a row */
+	long target_extra ;      /*!< amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
 } jb_conf;
 
 typedef struct jb_info {
 	jb_conf conf;
 
 	/* statistics */
-	long frames_in;  	/* number of frames input to the jitterbuffer.*/
-	long frames_out;  	/* number of frames output from the jitterbuffer.*/
-	long frames_late; 	/* number of frames which were too late, and dropped.*/
-	long frames_lost; 	/* number of missing frames.*/
-	long frames_dropped; 	/* number of frames dropped (shrinkage) */
-	long frames_ooo; 	/* number of frames received out-of-order */
-	long frames_cur; 	/* number of frames presently in jb, awaiting delivery.*/
-	long jitter; 		/* jitter measured within current history interval*/
-	long min;		/* minimum lateness within current history interval */
-	long current; 		/* the present jitterbuffer adjustment */
-	long target; 		/* the target jitterbuffer adjustment */
-	long losspct; 		/* recent lost frame percentage (* 1000) */
-	long next_voice_ts;	/* the ts of the next frame to be read from the jb - in receiver's time */
-	long last_voice_ms;	/* the duration of the last voice frame */
-	long silence_begin_ts;	/* the time of the last CNG frame, when in silence */
-	long last_adjustment;   /* the time of the last adjustment */
- 	long last_delay;        /* the last now added to history */
- 	long cnt_delay_discont;	/* the count of discontinuous delays */
- 	long resync_offset;     /* the amount to offset ts to support resyncs */
-	long cnt_contig_interp; /* the number of contiguous interp frames returned */
+	long frames_in;  	/*!< number of frames input to the jitterbuffer.*/
+	long frames_out;  	/*!< number of frames output from the jitterbuffer.*/
+	long frames_late; 	/*!< number of frames which were too late, and dropped.*/
+	long frames_lost; 	/*!< number of missing frames.*/
+	long frames_dropped; 	/*!< number of frames dropped (shrinkage) */
+	long frames_ooo; 	/*!< number of frames received out-of-order */
+	long frames_cur; 	/*!< number of frames presently in jb, awaiting delivery.*/
+	long jitter; 		/*!< jitter measured within current history interval*/
+	long min;		/*!< minimum lateness within current history interval */
+	long current; 		/*!< the present jitterbuffer adjustment */
+	long target; 		/*!< the target jitterbuffer adjustment */
+	long losspct; 		/*!< recent lost frame percentage (* 1000) */
+	long next_voice_ts;	/*!< the ts of the next frame to be read from the jb - in receiver's time */
+	long last_voice_ms;	/*!< the duration of the last voice frame */
+	long silence_begin_ts;	/*!< the time of the last CNG frame, when in silence */
+	long last_adjustment;   /*!< the time of the last adjustment */
+ 	long last_delay;        /*!< the last now added to history */
+ 	long cnt_delay_discont;	/*!< the count of discontinuous delays */
+ 	long resync_offset;     /*!< the amount to offset ts to support resyncs */
+	long cnt_contig_interp; /*!< the number of contiguous interp frames returned */
 } jb_info;
 
 typedef struct jb_frame {
@@ -99,15 +99,15 @@ typedef struct jitterbuf {
 	jb_info info;
 
 	/* history */
-	long history[JB_HISTORY_SZ];   		/* history */
-	int  hist_ptr;				/* points to index in history for next entry */
-	long hist_maxbuf[JB_HISTORY_MAXBUF_SZ];	/* a sorted buffer of the max delays (highest first) */
-	long hist_minbuf[JB_HISTORY_MAXBUF_SZ];	/* a sorted buffer of the min delays (lowest first) */
-	int  hist_maxbuf_valid;			/* are the "maxbuf"/minbuf valid? */
-	unsigned int dropem:1;                  /* flag to indicate dropping frames (overload) */
-
-	jb_frame *frames; 		/* queued frames */
-	jb_frame *free; 		/* free frames (avoid malloc?) */
+	long history[JB_HISTORY_SZ];   		/*!< history */
+	int  hist_ptr;				/*!< points to index in history for next entry */
+	long hist_maxbuf[JB_HISTORY_MAXBUF_SZ];	/*!< a sorted buffer of the max delays (highest first) */
+	long hist_minbuf[JB_HISTORY_MAXBUF_SZ];	/*!< a sorted buffer of the min delays (lowest first) */
+	int  hist_maxbuf_valid;			/*!< are the "maxbuf"/minbuf valid? */
+	unsigned int dropem:1;                  /*!< flag to indicate dropping frames (overload) */
+
+	jb_frame *frames; 		/*!< queued frames */
+	jb_frame *free; 		/*!< free frames (avoid malloc?) */
 } jitterbuf;
 
 
@@ -146,10 +146,10 @@ enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout);
  * This value may change as frames are added (esp non-audio frames) */
 long			jb_next(jitterbuf *jb);
 
-/* get jitterbuf info: only "statistics" may be valid */
+/*! get jitterbuf info: only "statistics" may be valid */
 enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats);
 
-/* set jitterbuf conf */
+/*! set jitterbuf conf */
 enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf);
 
 typedef 		void (*jb_output_function_t)(const char *fmt, ...);