[vlc-devel] [PATCH 3/5] libvlc: document the function to call to release some allocated structures

[Steve Lhomme]

---
 include/vlc/libvlc_media.h             | 2 ++
 include/vlc/libvlc_media_library.h     | 1 +
 include/vlc/libvlc_media_list_player.h | 2 ++
 include/vlc/libvlc_media_player.h      | 3 +++
 4 files changed, 8 insertions(+)

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index 8122a35e80..cd335a6e08 100644
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -835,6 +835,7 @@ typedef enum libvlc_thumbnailer_seek_speed_t
  * \param timeout A timeout value in ms, or 0 to disable timeout
  *
  * \return A valid opaque request object, or NULL in case of failure.
+ * It must be released by libvlc_media_thumbnail_cancel().
  *
  * \version libvlc 4.0 or later
  *
@@ -864,6 +865,7 @@ libvlc_media_thumbnail_request_by_time( libvlc_media_t *md,
  * \param timeout A timeout value in ms, or 0 to disable timeout
  *
  * \return A valid opaque request object, or NULL in case of failure.
+ * It must be released by libvlc_media_thumbnail_cancel().
  *
  * \version libvlc 4.0 or later
  *
diff --git a/include/vlc/libvlc_media_library.h b/include/vlc/libvlc_media_library.h
index a6ee1f41b9..49d4643fcc 100644
--- a/include/vlc/libvlc_media_library.h
+++ b/include/vlc/libvlc_media_library.h
@@ -43,6 +43,7 @@ typedef struct libvlc_media_library_t libvlc_media_library_t;
  *
  * \param p_instance the libvlc instance
  * \return a new object or NULL on error
+ *         (it must be released by libvlc_media_library_release())
  */
 LIBVLC_API libvlc_media_library_t *
     libvlc_media_library_new( libvlc_instance_t * p_instance );
diff --git a/include/vlc/libvlc_media_list_player.h b/include/vlc/libvlc_media_list_player.h
index 4fb7f31f50..57c1d0836d 100644
--- a/include/vlc/libvlc_media_list_player.h
+++ b/include/vlc/libvlc_media_list_player.h
@@ -56,6 +56,7 @@ typedef enum libvlc_playback_mode_t
  *
  * \param p_instance libvlc instance
  * \return media list player instance or NULL on error
+ *         (it must be released by libvlc_media_list_player_release())
  */
 LIBVLC_API libvlc_media_list_player_t *
     libvlc_media_list_player_new( libvlc_instance_t * p_instance );
@@ -107,6 +108,7 @@ LIBVLC_API void
  * \param p_mlp media list player instance
  * \return media player instance
  * \note the caller is responsible for releasing the returned instance
+         with libvlc_media_list_player_set_media_player().
  */
 LIBVLC_API libvlc_media_player_t *
     libvlc_media_list_player_get_media_player(libvlc_media_list_player_t * p_mlp);
diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h
index a2a032cb13..6f3af1b731 100644
--- a/include/vlc/libvlc_media_player.h
+++ b/include/vlc/libvlc_media_player.h
@@ -172,6 +172,7 @@ typedef struct libvlc_equalizer_t libvlc_equalizer_t;
  * \param p_libvlc_instance the libvlc instance in which the Media Player
  *        should be created.
  * \return a new media player object, or NULL on error.
+ * It must be released by libvlc_media_player_release().
  */
 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );
 
@@ -181,6 +182,7 @@ LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p
  * \param p_md the media. Afterwards the p_md can be safely
  *        destroyed.
  * \return a new media player object, or NULL on error.
+ * It must be released by libvlc_media_player_release().
  */
 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md );
 
@@ -2269,6 +2271,7 @@ LIBVLC_API libvlc_equalizer_t *libvlc_audio_equalizer_new( void );
  *
  * \param u_index index of the preset, counting from zero
  * \return opaque equalizer handle, or NULL on error
+ *         (it must be released with libvlc_audio_equalizer_release())
  * \version LibVLC 2.2.0 or later
  */
 LIBVLC_API libvlc_equalizer_t *libvlc_audio_equalizer_new_from_preset( unsigned u_index );
-- 
2.17.1