frame: Fix for Doxygen.

ASTERISK-29755

Change-Id: I8240013ec3db0669c0acf67e26bf6c9cbb5b72af

include/asterisk/audiohook.h

@@ -78,11 +78,12 @@ enum ast_audiohook_init_flags {
 struct ast_audiohook;
 
 /*! \brief Callback function for manipulate audiohook type
- * \param audiohook Audiohook structure
- * \param chan Channel
+ * \param audiohook
+ * \param chan
  * \param frame Frame of audio to manipulate
  * \param direction Direction frame came from
- * \return Returns 0 on success, -1 on failure.
+ * \retval 0 on success
+ * \retval -1 on failure
  * \note An audiohook does not have any reference to a private data structure for manipulate
  *       types. It is up to the manipulate callback to store this data via it's own method.
  *       An example would be datastores.
@@ -116,64 +117,69 @@ struct ast_audiohook {
 	struct ast_trans_pvt *trans_pvt;                       /*!< Translation path for reading frames */
 	ast_audiohook_manipulate_callback manipulate_callback; /*!< Manipulation callback */
 	struct ast_audiohook_options options;                  /*!< Applicable options */
-	unsigned int hook_internal_samp_rate;                           /*!< internal read/write sample rate on the audiohook.*/
+	unsigned int hook_internal_samp_rate;                  /*!< internal read/write sample rate on the audiohook.*/
 	AST_LIST_ENTRY(ast_audiohook) list;                    /*!< Linked list information */
 };
 
 struct ast_audiohook_list;
 
 /*! \brief Initialize an audiohook structure
- * \param audiohook Audiohook structure
+ * \param audiohook
  * \param type Type of audiohook to initialize this as
  * \param source Who is initializing this audiohook
- * \param init flags
- * \return Returns 0 on success, -1 on failure
+ * \param flags
+ * \retval 0 on success
+ * \retval -1 on failure
  */
 int ast_audiohook_init(struct ast_audiohook *audiohook, enum ast_audiohook_type type, const char *source, enum ast_audiohook_init_flags flags);
 
 /*! \brief Destroys an audiohook structure
- * \param audiohook Audiohook structure
- * \return Returns 0 on success, -1 on failure
+ * \param audiohook
+ * \retval 0 on success
+ * \retval -1 on failure
  */
 int ast_audiohook_destroy(struct ast_audiohook *audiohook);
 
 /*! \brief Writes a frame into the audiohook structure
- * \param audiohook Audiohook structure
+ * \param audiohook
  * \param direction Direction the audio frame came from
  * \param frame Frame to write in
- * \return Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
  */
 int ast_audiohook_write_frame(struct ast_audiohook *audiohook, enum ast_audiohook_direction direction, struct ast_frame *frame);
 
 /*! \brief Reads a frame in from the audiohook structure
- * \param audiohook Audiohook structure
+ * \param audiohook
  * \param samples Number of samples wanted
  * \param direction Direction the audio frame came from
  * \param format Format of frame remote side wants back
- * \return Returns frame on success, NULL on failure
+ * \return frame on success
+ * \retval NULL on failure
  */
 struct ast_frame *ast_audiohook_read_frame(struct ast_audiohook *audiohook, size_t samples, enum ast_audiohook_direction direction, struct ast_format *format);
 
 /*! \brief Reads a frame in from the audiohook structure in mixed audio mode and copies read and write frame data to provided arguments.
- * \param audiohook Audiohook structure
+ * \param audiohook
  * \param samples Number of samples wanted
- * \param ast_format Format of frame remote side wants back
+ * \param format Format of frame remote side wants back
  * \param read_frame if available, we'll copy the read buffer to this.
  * \param write_frame if available, we'll copy the write buffer to this.
- * \param direction
- * \return Returns frame on success, NULL on failure
+ * \return frame on success
+ * \retval NULL on failure
  */
 struct ast_frame *ast_audiohook_read_frame_all(struct ast_audiohook *audiohook, size_t samples, struct ast_format *format, struct ast_frame **read_frame, struct ast_frame **write_frame);
 
 /*! \brief Attach audiohook to channel
- * \param chan Channel
- * \param audiohook Audiohook structure
- * \return Returns 0 on success, -1 on failure
+ * \param chan
+ * \param audiohook
+ * \return 0 on success
+ * \retval -1 on failure
  */
 int ast_audiohook_attach(struct ast_channel *chan, struct ast_audiohook *audiohook);
 
 /*! \brief Detach audiohook from channel
- * \param audiohook Audiohook structure
+ * \param audiohook
  * \return Returns 0 on success, -1 on failure
  */
 int ast_audiohook_detach(struct ast_audiohook *audiohook);
@@ -181,7 +187,6 @@ int ast_audiohook_detach(struct ast_audiohook *audiohook);
 /*!
  * \brief Detach audiohooks from list and destroy said list
  * \param audiohook_list List of audiohooks (NULL tolerant)
- * \return Nothing
  */
 void ast_audiohook_detach_list(struct ast_audiohook_list *audiohook_list);
 
@@ -217,7 +222,8 @@ void ast_audiohook_move_all(struct ast_channel *old_chan, struct ast_channel *ne
  * \param chan Channel to detach from
  * \param source Name of source to detach
  *
- * \return Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
  *
  * \note The channel does not need to be locked before calling this function.
  */
@@ -229,7 +235,8 @@ int ast_audiohook_detach_source(struct ast_channel *chan, const char *source);
  * \param chan Channel to remove from
  * \param audiohook Audiohook to remove
  *
- * \return Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
  *
  * \note The channel does not need to be locked before calling this function
  */
@@ -238,9 +245,10 @@ int ast_audiohook_remove(struct ast_channel *chan, struct ast_audiohook *audioho
 /*!
  * \brief Determine if a audiohook_list is empty or not.
  *
- * \param audiohook Audiohook to check.  (NULL also means empty)
+ * \param audiohook_list Audiohook to check.  (NULL also means empty)
  *
- * retval 0 false, 1 true
+ * \retval 0 false
+ * \retval 1 true
  */
 int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
 
@@ -249,13 +257,14 @@ int ast_audiohook_write_list_empty(struct ast_audiohook_list *audiohook_list);
  * \param audiohook_list List of audiohooks
  * \param direction Direction frame is coming in from
  * \param frame The frame itself
- * \return Return frame on success, NULL on failure
+ * \return frame on success
+ * \retval NULL on failure
  */
 struct ast_frame *ast_audiohook_write_list(struct ast_channel *chan, struct ast_audiohook_list *audiohook_list, enum ast_audiohook_direction direction, struct ast_frame *frame);
 
 /*! \brief Update audiohook's status
- * \param audiohook Audiohook structure
- * \param audiohook status enum
+ * \param audiohook
+ * \param status
  *
  * \note once status is updated to DONE, this function can not be used to set the
  * status back to any other setting.  Setting DONE effectively locks the status as such.
@@ -272,7 +281,7 @@ void ast_audiohook_trigger_wait(struct ast_audiohook *audiohook);
   \param chan The channel on which to find the spies
   \param source The audiohook's source
   \param type The type of audiohook
-  \return Return the number of audiohooks which are from the source specified
+  \return number of audiohooks which are from the source specified
 
   Note: Function performs nlocking.
 */
@@ -283,7 +292,7 @@ int ast_channel_audiohook_count_by_source(struct ast_channel *chan, const char *
   \param chan The channel on which to find the spies
   \param source The source of the audiohook
   \param type The type of spy to look for
-  \return Return the number of running audiohooks which are from the source specified
+  \return number of running audiohooks which are from the source specified
 
   Note: Function performs no locking.
 */
@@ -304,7 +313,8 @@ int ast_channel_audiohook_count_by_source_running(struct ast_channel *chan, cons
  * \param chan Channel to muck with
  * \param direction Direction to set on
  * \param volume Value to adjust the volume by
- * \return Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
  * \since 1.6.1
  */
 int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);
@@ -313,7 +323,7 @@ int ast_audiohook_volume_set(struct ast_channel *chan, enum ast_audiohook_direct
  * \brief Retrieve the volume adjustment value on frames read from or written to a channel
  * \param chan Channel to retrieve volume adjustment from
  * \param direction Direction to retrieve
- * \return Returns adjustment value
+ * \return adjustment value
  * \since 1.6.1
  */
 int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direction direction);
@@ -323,7 +333,8 @@ int ast_audiohook_volume_get(struct ast_channel *chan, enum ast_audiohook_direct
  * \param chan Channel to muck with
  * \param direction Direction to increase
  * \param volume Value to adjust the adjustment by
- * \return Returns 0 on success, -1 on failure
+ * \retval 0 on success
+ * \retval -1 on failure
  * \since 1.6.1
  */
 int ast_audiohook_volume_adjust(struct ast_channel *chan, enum ast_audiohook_direction direction, int volume);

include/asterisk/frame.h

@@ -531,23 +531,23 @@ struct ast_option_header {
 		uint8_t data[0];
 };
 
+#if 0 /* Unimplemented */
 /*! \brief  Requests a frame to be allocated
  *
- * \param source
+ * \param source, len
  * Request a frame be allocated.  source is an optional source of the frame,
  * len is the requested length, or "0" if the caller will supply the buffer
  */
-#if 0 /* Unimplemented */
 struct ast_frame *ast_fralloc(char *source, int len);
 #endif
 
 /*!
  * \brief Frees a frame or list of frames
  *
- * \param fr Frame to free, or head of list to free
+ * \param frame Frame to free, or head of list to free
  * \param cache Whether to consider this frame for frame caching
  */
-void ast_frame_free(struct ast_frame *fr, int cache);
+void ast_frame_free(struct ast_frame *frame, int cache);
 
 #define ast_frfree(fr) ast_frame_free(fr, 1)
 

include/asterisk/framehook.h

@@ -174,12 +174,12 @@ enum ast_framehook_event {
  * The ast_channel will always be locked during this callback. Never attempt to unlock the
  * channel for any reason.
  *
- * \param channel, The ast_channel this framehook is attached to
- * \param frame, The ast_frame being intercepted for viewing and manipulation
- * \param event, The type of event which is occurring
- * \param data, The data pointer provided at framehook initialization.
+ * \param chan The ast_channel this framehook is attached to
+ * \param frame The ast_frame being intercepted for viewing and manipulation
+ * \param event The type of event which is occurring
+ * \param data The data pointer provided at framehook initialization.
  *
- * \retval the resulting frame.
+ * \return the resulting frame.
  */
 typedef struct ast_frame *(*ast_framehook_event_callback)(
 	struct ast_channel *chan,
@@ -193,7 +193,7 @@ typedef struct ast_frame *(*ast_framehook_event_callback)(
  * \note  This function should be used to clean up any pointers pointing to the
  * framehook structure as the framehook will be freed immediately afterwards.
  *
- * \param data, The data pointer provided at framehook initialization. This
+ * \param data The data pointer provided at framehook initialization. This
  * is a good place to clean up any state data allocated for the framehook stored in this
  * pointer.
  */
@@ -204,8 +204,8 @@ typedef void (*ast_framehook_destroy_callback)(void *data);
  * frames of a given type
  * \since 12
  *
- * \param data, The data pointer provided at framehook initialization.
- * \param type, The type of frame.
+ * \param data The data pointer provided at framehook initialization.
+ * \param type The type of frame.
  *
  * \return 0 if frame type is being ignored
  * \return 1 if frame type is not being ignored
@@ -216,10 +216,10 @@ typedef int (*ast_framehook_consume_callback)(void *data, enum ast_frame_type ty
  * \brief This callback is called when a masquerade occurs on a channel with a framehook
  * \since 12
  *
- * \param data, The data pointer provided at framehook initialization.
- * \param framehook_id, The framehook ID where the framehook lives now
- * \param old_chan, The channel that was masqueraded.
- * \param new_chan, The channel that the masqueraded channel became.
+ * \param data The data pointer provided at framehook initialization.
+ * \param framehook_id The framehook ID where the framehook lives now
+ * \param old_chan The channel that was masqueraded.
+ * \param new_chan The channel that the masqueraded channel became.
  */
 typedef void (*ast_framehook_chan_fixup_callback)(void *data, int framehook_id,
 	struct ast_channel *old_chan, struct ast_channel *new_chan);
@@ -268,8 +268,8 @@ struct ast_framehook_interface {
  * provide it during the event and destruction callbacks.  It is entirely up to the
  * application using this API to manage the memory associated with the data pointer.
  *
- * \retval On success, non-negative id representing this hook on the channel
- * \retval On failure, -1
+ * \retval non-negative success, id representing this hook on the channel
+ * \retval -1 failure
  */
 int ast_framehook_attach(struct ast_channel *chan, struct ast_framehook_interface *i);
 
@@ -356,8 +356,8 @@ struct ast_frame *ast_framehook_list_write_event(struct ast_framehook_list *fram
  * \pre The Channel must be locked during this function call.
  *
  * \param framehooks the framehook list
- * \retval 0, not empty
- * \retval 1, is empty
+ * \retval 0 not empty
+ * \retval 1 is empty
  */
 int ast_framehook_list_is_empty(struct ast_framehook_list *framehooks);
 
@@ -367,8 +367,8 @@ int ast_framehook_list_is_empty(struct ast_framehook_list *framehooks);
  * \pre The channel must be locked during this function call.
  *
  * \param framehooks the framehook list
- * \retval 0, not empty
- * \retval 1, is empty (aside from dying framehooks)
+ * \retval 0 not empty
+ * \retval 1 is empty (aside from dying framehooks)
  *
  * \note This function is very similar to ast_framehook_list_is_empty, but it checks individual
  *       framehooks to see if they have been marked for destruction and doesn't count them if they are.
@@ -381,8 +381,9 @@ int ast_framehook_list_contains_no_active(struct ast_framehook_list *framehooks)
  * \pre The channel must be locked during this function call.
  *
  * \param framehooks the framehook list
- * \retval 0, not empty
- * \retval 1, is empty (aside from dying framehooks)
+ * \param type type of frame
+ * \retval 0 not empty
+ * \retval 1 is empty (aside from dying framehooks)
  *
  * \note This function is very similar to ast_framehook_list_is_empty, but it checks individual
  *       framehooks to see if they have been marked for destruction and doesn't count them if they are.