Improve Doxygen documentation, deobfuscate event types

[vlc] / include / vlc / libvlc_media.h

diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h
index 9d9d810969bf7d631d75e989f34dc82b71413d25..075a1c670f32db3c7bcd16080a1f0b7a37eb1cb5 100644 (file)
--- a/include/vlc/libvlc_media.h
+++ b/include/vlc/libvlc_media.h
@@ -35,24 +35,21 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * media
- *****************************************************************************/
-/** \defgroup libvlc_media libvlc_media
+/** \defgroup libvlc_media LibVLC media
  * \ingroup libvlc
- * LibVLC Media
+ * @ref libvlc_media_t is an abstract representation of a playable media.
+ * It consists of a media location and various optional meta data.
  * @{
  */
 
 typedef struct libvlc_media_t libvlc_media_t;
 
-/* Meta Handling */
-/** defgroup libvlc_meta libvlc_meta
+/** defgroup libvlc_meta LibVLC meta data
  * \ingroup libvlc_media
- * LibVLC Media Meta
  * @{
  */
 
+/** Meta data types */
 typedef enum libvlc_meta_t {
     libvlc_meta_Title,
     libvlc_meta_Artist,
@@ -97,11 +94,11 @@ typedef enum libvlc_state_t
     libvlc_Error
 } libvlc_state_t;
 
-typedef enum libvlc_media_option_t
+enum
 {
     libvlc_media_option_trusted = 0x2,
     libvlc_media_option_unique = 0x100
-} libvlc_media_option_t;
+};
 
 typedef enum libvlc_es_type_t
 {
@@ -111,9 +108,8 @@ typedef enum libvlc_es_type_t
     libvlc_es_text      = 2,
 } libvlc_es_type_t;
 
-/** defgroup libvlc_media_stats_t libvlc_media_stats_t
+/** defgroup libvlc_media_stats_t LibVLC media statistics
  * \ingroup libvlc_media
- * LibVLC Media statistics
  * @{
  */
 typedef struct libvlc_media_stats_t
@@ -170,16 +166,27 @@ typedef struct libvlc_media_es_t
 
 
 /**
- * Create a media with the given MRL.
+ * Create a media with a certain given media resource location.
  *
  * \param p_instance the instance
  * \param psz_mrl the MRL to read
  * \return the newly created media or NULL on error
  */
-VLC_PUBLIC_API libvlc_media_t * libvlc_media_new(
+VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location(
                                    libvlc_instance_t *p_instance,
                                    const char * psz_mrl );
 
+/**
+ * Create a media with a certain file path.
+ *
+ * \param p_instance the instance
+ * \param path local filesystem path
+ * \return the newly created media or NULL on error
+ */
+VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path(
+                                   libvlc_instance_t *p_instance,
+                                   const char *path );
+
 /**
  * Create a media as an empty node with a given name.
  *
@@ -223,7 +230,7 @@ VLC_PUBLIC_API void libvlc_media_add_option(
 VLC_PUBLIC_API void libvlc_media_add_option_flag(
                                    libvlc_media_t * p_md,
                                    const char * ppsz_options,
-                                   libvlc_media_option_t i_flags );
+                                   unsigned i_flags );
 
 
 /**
@@ -258,7 +265,7 @@ VLC_PUBLIC_API char * libvlc_media_get_mrl( libvlc_media_t * p_md );
 /**
  * Duplicate a media descriptor object.
  *
- * \param p_meta_desc a media descriptor object.
+ * \param p_md a media descriptor object.
  */
 VLC_PUBLIC_API libvlc_media_t * libvlc_media_duplicate( libvlc_media_t *p_md );
 
@@ -278,7 +285,7 @@ VLC_PUBLIC_API char * libvlc_media_get_meta( libvlc_media_t *p_md,
  *
  * \param p_md the media descriptor
  * \param e_meta the meta to write
- * \param the media's meta
+ * \param psz_value the media's meta
  */
 VLC_PUBLIC_API void libvlc_media_set_meta( libvlc_media_t *p_md,
                                            libvlc_meta_t e_meta,
@@ -393,7 +400,7 @@ VLC_PUBLIC_API void *
  * will duplicate the entries in the array each time.
  *
  * \param p_md media descriptor object
- * \param pp_es adress to store an allocated array of Elementary Streams descriptions (must be freed by the caller)
+ * \param pp_es address to store an allocated array of Elementary Streams descriptions (must be freed by the caller)
  *
  * return the number of Elementary Streams
  */