vlc_decoder.h: document vlc_input_decoder_Delete

Add documentation for the vlc_input_decoder_Delete function to enforce
usage of vlc_input_decoder_Flush or vlc_input_decoder_Drain before
destruction.

include/vlc_decoder.h

@@ -43,7 +43,21 @@ struct vlc_clock_t;
 VLC_API vlc_input_decoder_t *
 vlc_input_decoder_Create( vlc_object_t *, const es_format_t *,
                           struct vlc_clock_t *, input_resource_t * ) VLC_USED;
-VLC_API void vlc_input_decoder_Delete( vlc_input_decoder_t * );
+
+/**
+ * Delete an existing vlc_input_decoder_t instance.
+ *
+ * Close the decoder implementation and delete the vlc_input_decoder_t
+ * instance.
+ * The instance must have been drained using vlc_input_decoder_Drain() or
+ * flushed using vlc_input_decoder_Flush() after any previous call to
+ * vlc_input_decoder_Decode() before calling the destructor.
+ *
+ * @param decoder The vlc_input_decoder_t to delete, created from
+ *        vlc_input_decoder_Create().
+ */
+VLC_API void vlc_input_decoder_Delete( vlc_input_decoder_t * decoder);
+
 VLC_API void vlc_input_decoder_Decode( vlc_input_decoder_t *, block_t *, bool b_do_pace );
 VLC_API void vlc_input_decoder_Drain( vlc_input_decoder_t * );
 VLC_API void vlc_input_decoder_Flush( vlc_input_decoder_t * );