[vlc-devel] [PATCH 04/19] decoder: move documentation to vlc_decoder.h

[Kartik Ohri]

Move documentation for VLC API methods
vlc_input_decoder_Create, vlc_input_decoder_Delete,
vlc_input_decoder_Decode, vlc_input_decoder_Drain and
vlc_input_decoder_Flush from src/input/decoder.c to
include/vlc_decoder.h.
---
 include/vlc_decoder.h | 35 ++++++++++++++++++++++++++++++++++-
 src/input/decoder.c   | 30 ------------------------------
 2 files changed, 34 insertions(+), 31 deletions(-)

diff --git a/include/vlc_decoder.h b/include/vlc_decoder.h
index 94cceda61a..0df617e01c 100644
--- a/include/vlc_decoder.h
+++ b/include/vlc_decoder.h
@@ -38,13 +38,46 @@ typedef struct vlc_input_decoder_t vlc_input_decoder_t;
  */
 typedef struct input_resource_t input_resource_t;
 
-/* */
+/**
+ * Spawn a decoder thread outside of the input thread.
+ */
 VLC_API vlc_input_decoder_t *
 vlc_input_decoder_Create( vlc_object_t *, const es_format_t *, input_resource_t * ) VLC_USED;
+
+/**
+ * Kills a decoder thread and waits until it's finished
+ *
+ * \param p_input the input thread
+ * \param p_es the es descriptor
+ * \return nothing
+ */
 VLC_API void vlc_input_decoder_Delete( vlc_input_decoder_t * );
+
+/**
+ * Put a block_t in the decoder's fifo.
+ * Thread-safe w.r.t. the decoder. May be a cancellation point.
+ *
+ * \param p_dec the decoder object
+ * \param p_block the data block
+ */
 VLC_API void vlc_input_decoder_Decode( vlc_input_decoder_t *, block_t *, bool b_do_pace );
+
+/**
+ * Signals that there are no further blocks to decode, and requests that the
+ * decoder drain all pending buffers. This is used to ensure that all
+ * intermediate buffers empty and no samples get lost at the end of the stream.
+ *
+ * @note The function does not actually wait for draining. It just signals that
+ * draining should be performed once the decoder has emptied FIFO.
+ */
 VLC_API void vlc_input_decoder_Drain( vlc_input_decoder_t * );
+
+/**
+ * Requests that the decoder immediately discard all pending buffers.
+ * This is useful when seeking or when deselecting a stream.
+ */
 VLC_API void vlc_input_decoder_Flush( vlc_input_decoder_t * );
+
 VLC_API int  vlc_input_decoder_SetSpuHighlight( vlc_input_decoder_t *, const vlc_spu_highlight_t * );
 
 /**
diff --git a/src/input/decoder.c b/src/input/decoder.c
index 141120d639..3d981521db 100644
--- a/src/input/decoder.c
+++ b/src/input/decoder.c
@@ -2108,9 +2108,6 @@ vlc_input_decoder_New( vlc_object_t *parent, es_format_t *fmt,
                         cbs, cbs_userdata );
 }
 
-/**
- * Spawn a decoder thread outside of the input thread.
- */
 vlc_input_decoder_t *
 vlc_input_decoder_Create( vlc_object_t *p_parent, const es_format_t *fmt,
                      input_resource_t *p_resource )
@@ -2119,14 +2116,6 @@ vlc_input_decoder_Create( vlc_object_t *p_parent, const es_format_t *fmt,
                         NULL );
 }
 
-
-/**
- * Kills a decoder thread and waits until it's finished
- *
- * \param p_input the input thread
- * \param p_es the es descriptor
- * \return nothing
- */
 void vlc_input_decoder_Delete( vlc_input_decoder_t *p_owner )
 {
     decoder_t *p_dec = &p_owner->dec;
@@ -2169,13 +2158,6 @@ void vlc_input_decoder_Delete( vlc_input_decoder_t *p_owner )
     DeleteDecoder( p_owner );
 }
 
-/**
- * Put a block_t in the decoder's fifo.
- * Thread-safe w.r.t. the decoder. May be a cancellation point.
- *
- * \param p_dec the decoder object
- * \param p_block the data block
- */
 void vlc_input_decoder_Decode( vlc_input_decoder_t *p_owner, block_t *p_block,
                                bool b_do_pace )
 {
@@ -2237,14 +2219,6 @@ bool vlc_input_decoder_IsEmpty( vlc_input_decoder_t * p_owner )
     return b_empty;
 }
 
-/**
- * Signals that there are no further blocks to decode, and requests that the
- * decoder drain all pending buffers. This is used to ensure that all
- * intermediate buffers empty and no samples get lost at the end of the stream.
- *
- * @note The function does not actually wait for draining. It just signals that
- * draining should be performed once the decoder has emptied FIFO.
- */
 void vlc_input_decoder_Drain( vlc_input_decoder_t *p_owner )
 {
     vlc_fifo_Lock( p_owner->p_fifo );
@@ -2253,10 +2227,6 @@ void vlc_input_decoder_Drain( vlc_input_decoder_t *p_owner )
     vlc_fifo_Unlock( p_owner->p_fifo );
 }
 
-/**
- * Requests that the decoder immediately discard all pending buffers.
- * This is useful when seeking or when deselecting a stream.
- */
 void vlc_input_decoder_Flush( vlc_input_decoder_t *p_owner )
 {
     vlc_fifo_Lock( p_owner->p_fifo );
-- 
2.25.1