[svn-commits] file: trunk r108226 - in /trunk: include/asterisk/ main/

[SVN commits to the Digium repositories]

Author: file
Date: Wed Mar 12 16:06:50 2008
New Revision: 108226

URL: http://svn.digium.com/view/asterisk?view=rev&rev=108226
Log:
Doxygenify slinfactory a bit.

Modified:
    trunk/include/asterisk/slinfactory.h
    trunk/main/slinfactory.c

Modified: trunk/include/asterisk/slinfactory.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/slinfactory.h?view=diff&rev=108226&r1=108225&r2=108226
==============================================================================
--- trunk/include/asterisk/slinfactory.h (original)
+++ trunk/include/asterisk/slinfactory.h Wed Mar 12 16:06:50 2008
@@ -29,33 +29,74 @@
 #endif
 
 struct ast_slinfactory {
-	AST_LIST_HEAD_NOLOCK(, ast_frame) queue;
-	struct ast_trans_pvt *trans;
-	short hold[1280];
-	short *offset;
-	size_t holdlen;			/*!< in samples */
-	unsigned int size;		/*!< in samples */
-	unsigned int format;
+	AST_LIST_HEAD_NOLOCK(, ast_frame) queue; /*!< A list of unaltered frames */
+	struct ast_trans_pvt *trans;             /*!< Translation path that converts fed frames into signed linear */
+	short hold[1280];                        /*!< Hold for audio that no longer belongs to a frame (ie: if only some samples were taken from a frame) */
+	short *offset;                           /*!< Offset into the hold where audio begins */
+	size_t holdlen;                          /*!< Number of samples currently in the hold */
+	unsigned int size;                       /*!< Number of samples currently in the factory */
+	unsigned int format;                     /*!< Current format the translation path is converting from */
 };
 
+/*!
+ * \brief Initialize an slinfactory
+ *
+ * \arg sf The slinfactory to initialize
+ *
+ * \return Nothing
+ */
 void ast_slinfactory_init(struct ast_slinfactory *sf);
 
 /*!
  * \brief Destroy the contents of a slinfactory
  *
- * \arg sf the slinfactory that is no longer needed
+ * \arg sf The slinfactory that is no longer needed
  *
  * This function will free any memory allocated for the contents of the
  * slinfactory.  It does not free the slinfactory itself.  If the sf is
  * malloc'd, then it must be explicitly free'd after calling this function.
  *
- * \return nothing
+ * \return Nothing
  */
 void ast_slinfactory_destroy(struct ast_slinfactory *sf);
 
+/*!
+ * \brief Feed audio into an slinfactory
+ *
+ * \arg sf The slinfactory to feed into
+ * \arg f Frame containing audio to feed in
+ *
+ * \return Number of frames currently in factory
+ */
 int ast_slinfactory_feed(struct ast_slinfactory *sf, struct ast_frame *f);
+
+/*!
+ * \brief Read samples from an slinfactory
+ *
+ * \arg sf The slinfactory to read from
+ * \arg buf Buffer to put samples into
+ * \arg samples Number of samples wanted
+ *
+ * \return Number of samples read
+ */
 int ast_slinfactory_read(struct ast_slinfactory *sf, short *buf, size_t samples);
+
+/*!
+ * \brief Retrieve number of samples currently in an slinfactory
+ *
+ * \arg sf The slinfactory to peek into
+ *
+ * \return Number of samples in slinfactory
+ */
 unsigned int ast_slinfactory_available(const struct ast_slinfactory *sf);
+
+/*!
+ * \brief Flush the contents of an slinfactory
+ *
+ * \arg sf The slinfactory to flush
+ *
+ * \return Nothing
+ */
 void ast_slinfactory_flush(struct ast_slinfactory *sf);
 
 #if defined(__cplusplus) || defined(c_plusplus)

Modified: trunk/main/slinfactory.c
URL: http://svn.digium.com/view/asterisk/trunk/main/slinfactory.c?view=diff&rev=108226&r1=108225&r2=108226
==============================================================================
--- trunk/main/slinfactory.c (original)
+++ trunk/main/slinfactory.c Wed Mar 12 16:06:50 2008
@@ -32,12 +32,30 @@
 #include "asterisk/slinfactory.h"
 #include "asterisk/translate.h"
 
+/*!
+ * \brief Initialize an slinfactory
+ *
+ * \arg sf The slinfactory to initialize
+ *
+ * \return Nothing
+ */
 void ast_slinfactory_init(struct ast_slinfactory *sf) 
 {
 	memset(sf, 0, sizeof(*sf));
 	sf->offset = sf->hold;
 }
 
+/*!
+ * \brief Destroy the contents of a slinfactory
+ *
+ * \arg sf The slinfactory that is no longer needed
+ *
+ * This function will free any memory allocated for the contents of the
+ * slinfactory.  It does not free the slinfactory itself.  If the sf is
+ * malloc'd, then it must be explicitly free'd after calling this function.
+ *
+ * \return Nothing
+ */
 void ast_slinfactory_destroy(struct ast_slinfactory *sf) 
 {
 	struct ast_frame *f;
@@ -51,6 +69,14 @@
 		ast_frfree(f);
 }
 
+/*!
+ * \brief Feed audio into an slinfactory
+ *
+ * \arg sf The slinfactory to feed into
+ * \arg f Frame containing audio to feed in
+ *
+ * \return Number of frames currently in factory
+ */
 int ast_slinfactory_feed(struct ast_slinfactory *sf, struct ast_frame *f)
 {
 	struct ast_frame *begin_frame = f, *duped_frame = NULL, *frame_ptr;
@@ -99,6 +125,15 @@
 	return x;
 }
 
+/*!
+ * \brief Read samples from an slinfactory
+ *
+ * \arg sf The slinfactory to read from
+ * \arg buf Buffer to put samples into
+ * \arg samples Number of samples wanted
+ *
+ * \return Number of samples read
+ */
 int ast_slinfactory_read(struct ast_slinfactory *sf, short *buf, size_t samples) 
 {
 	struct ast_frame *frame_ptr;
@@ -150,11 +185,25 @@
 	return sofar;
 }
 
+/*!
+ * \brief Retrieve number of samples currently in an slinfactory
+ *
+ * \arg sf The slinfactory to peek into
+ *
+ * \return Number of samples in slinfactory
+ */
 unsigned int ast_slinfactory_available(const struct ast_slinfactory *sf)
 {
 	return sf->size;
 }
 
+/*!
+ * \brief Flush the contents of an slinfactory
+ *
+ * \arg sf The slinfactory to flush
+ *
+ * \return Nothing
+ */
 void ast_slinfactory_flush(struct ast_slinfactory *sf)
 {
 	struct ast_frame *fr = NULL;