Doxygen improvements

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

1 files changed, 42 insertions, 37 deletions

diff --git a/include/asterisk/translate.h b/include/asterisk/translate.h
index d1431b3be..182330ace 100644
--- a/include/asterisk/translate.h
+++ b/include/asterisk/translate.h
@@ -38,14 +38,15 @@ extern "C" {
 
 struct ast_trans_pvt;	/* declared below */
 
-/*!
+/*! \brief
  * Descriptor of a translator. Name, callbacks, and various options
  * related to run-time operation (size of buffers, auxiliary
  * descriptors, etc).
+ *
  * A coded registers itself by filling the relevant fields
  * of a structure and passing it as an argument to
  * ast_register_translator(). The structure should not be
- * modified after a successful register(), and its address
+ * modified after a successful registration, and its address
  * must be used as an argument to ast_unregister_translator().
  *
  * As a minimum, a translator should supply name, srcfmt and dstfmt,
@@ -64,49 +65,52 @@ struct ast_trans_pvt;	/* declared below */
  * Generic plc is only available for dstfmt = SLINEAR
  */
 struct ast_translator {
-	const char name[80];		/*! Name of translator */
-	int srcfmt;			/*! Source format (note: bit position,
+	const char name[80];		/*!< Name of translator */
+	int srcfmt;			/*!< Source format (note: bit position,
 					  converted to index during registration) */
-	int dstfmt;			/*! Destination format (note: bit position,
+	int dstfmt;			/*!< Destination format (note: bit position,
 					  converted to index during registration) */
 
-	/*! initialize private data associated with the translator */
-	void *(*newpvt)(struct ast_trans_pvt *);
+	void *(*newpvt)(struct ast_trans_pvt *); /*!< initialize private data 
+					associated with the translator */
 
-	/*! Input frame callback. Store (and possibly convert) input frame. */
 	int (*framein)(struct ast_trans_pvt *pvt, struct ast_frame *in);
+					/*!< Input frame callback. Store 
+					     (and possibly convert) input frame. */
 
-	/*! Output frame callback. Generate a frame with outbuf content. */
 	struct ast_frame * (*frameout)(struct ast_trans_pvt *pvt);
+					/*!< Output frame callback. Generate a frame 
+					    with outbuf content. */
 
-	/*! cleanup private data, if needed (often unnecessary). */
 	void (*destroy)(struct ast_trans_pvt *pvt);
+					/*!< cleanup private data, if needed 
+						(often unnecessary). */
 
-	struct ast_frame * (*sample)(void);	/*! Generate an example frame */
+	struct ast_frame * (*sample)(void);	/*!< Generate an example frame */
 
-	/*! size of outbuf, in samples. Leave it 0 if you want the framein
+	/*! \brief size of outbuf, in samples. Leave it 0 if you want the framein
 	 * callback deal with the frame. Set it appropriately if you
 	 * want the code to checks if the incoming frame fits the
 	 * outbuf (this is e.g. required for plc).
 	 */
-	int buffer_samples;	/* size of outbuf, in samples */
+	int buffer_samples;	/*< size of outbuf, in samples */
 
-	/*! size of outbuf, in bytes. Mandatory. The wrapper code will also
+	/*! \brief size of outbuf, in bytes. Mandatory. The wrapper code will also
 	 * allocate an AST_FRIENDLY_OFFSET space before.
 	 */
 	int buf_size;
 
-	int desc_size;		/*! size of private descriptor in pvt->pvt, if any */
-	int plc_samples;	/* set to the plc block size if used, 0 otherwise */
-	int useplc;		/* current status of plc, changed at runtime */
+	int desc_size;		/*!< size of private descriptor in pvt->pvt, if any */
+	int plc_samples;	/*!< set to the plc block size if used, 0 otherwise */
+	int useplc;		/*!< current status of plc, changed at runtime */
 
-	void *module;		/* opaque reference to the parent module */
+	void *module;		/*!< opaque reference to the parent module */
 
-	int cost;		/*! Cost in milliseconds for encoding/decoding 1 second of sound */
-	AST_LIST_ENTRY(ast_translator) list;	/*! link field */
+	int cost;		/*!< Cost in milliseconds for encoding/decoding 1 second of sound */
+	AST_LIST_ENTRY(ast_translator) list;	/*!< link field */
 };
 
-/*
+/*! \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.
@@ -126,18 +130,18 @@ struct ast_translator {
  */
 struct ast_trans_pvt {
 	struct ast_translator *t;
-	struct ast_frame f;	/* used in frameout */
-	int samples;		/* samples available in outbuf */
-	int datalen;		/* actual space used in outbuf */
-	void *pvt;		/* more private data, if any */
-	char *outbuf;		/* the useful portion of the buffer */
-	plc_state_t *plc;	/* optional plc pointer */
-	struct ast_trans_pvt *next;	/* next in translator chain */
+	struct ast_frame f;	/*!< used in frameout */
+	int samples;		/*!< samples available in outbuf */
+	int datalen;		/*!< actual space used in outbuf */
+	void *pvt;		/*!< more private data, if any */
+	char *outbuf;		/*!< the useful portion of the buffer */
+	plc_state_t *plc;	/*!< optional plc pointer */
+	struct ast_trans_pvt *next;	/*!< next in translator chain */
 	struct timeval nextin;
 	struct timeval nextout;
 };
 
-/* generic frameout function */
+/*! \brief generic frameout function */
 struct ast_frame *ast_trans_frameout(struct ast_trans_pvt *pvt,
         int datalen, int samples);
 
@@ -145,17 +149,17 @@ struct ast_trans_pvt;
 
 /*!
  * \brief Register a translator
+ * This registers a codec translator with asterisk
  * \param t populated ast_translator structure
  * \param module handle to the module that owns this translator
- * This registers a codec translator with asterisk
  * \return 0 on success, -1 on failure
  */
 int ast_register_translator(struct ast_translator *t, void *module);
 
 /*!
  * \brief Unregister a translator
- * \param t translator to unregister
  * Unregisters the given tranlator
+ * \param t translator to unregister
  * \return 0 on success, -1 on failure
  */
 int ast_unregister_translator(struct ast_translator *t);
@@ -164,34 +168,35 @@ int ast_unregister_translator(struct ast_translator *t);
  * \brief Chooses the best translation path
  *
  * Given a list of sources, and a designed destination format, which should
- * I choose? Returns 0 on success, -1 if no path could be found.  Modifies
- * dests and srcs in place 
+ * I choose? 
+ * \return Returns 0 on success, -1 if no path could be found.  
+ * \note Modifies dests and srcs in place 
  */
 int ast_translator_best_choice(int *dsts, int *srcs);
 
 /*! 
  * \brief Builds a translator path
+ * Build a path (possibly NULL) from source to dest 
  * \param dest destination format
  * \param source source format
- * Build a path (possibly NULL) from source to dest 
  * \return ast_trans_pvt on success, NULL on failure
  * */
 struct ast_trans_pvt *ast_translator_build_path(int dest, int source);
 
 /*!
  * \brief Frees a translator path
- * \param tr translator path to get rid of
  * Frees the given translator path structure
+ * \param tr translator path to get rid of
  */
 void ast_translator_free_path(struct ast_trans_pvt *tr);
 
 /*!
  * \brief translates one or more frames
+ * Apply an input frame into the translator and receive zero or one output frames.  Consume
+ * determines whether the original frame should be freed
  * \param tr translator structure to use for translation
  * \param f frame to translate
  * \param consume Whether or not to free the original frame
- * Apply an input frame into the translator and receive zero or one output frames.  Consume
- * determines whether the original frame should be freed
  * \return an ast_frame of the new translation format on success, NULL on failure
  */
 struct ast_frame *ast_translate(struct ast_trans_pvt *tr, struct ast_frame *f, int consume);