Improve Doxygen documentation, deobfuscate event types

include/vlc/deprecated.h

@@ -37,10 +37,9 @@ extern "C" {
 /*****************************************************************************
  * Playlist (Deprecated)
  *****************************************************************************/
-/** \defgroup libvlc_playlist libvlc_playlist (Deprecated)
+/** \defgroup libvlc_playlist LibVLC playlist (legacy)
  * \ingroup libvlc
- * LibVLC Playlist handling (Deprecated)
- * @deprecated Use media_list
+ * @deprecated Use @ref libvlc_media_list instead.
  * @{
  */
 

include/vlc/libvlc.h

@@ -29,9 +29,9 @@
  */
 
 /**
- * \defgroup libvlc libvlc
- * This is libvlc, the base library of the VLC program.
- *
+ * \defgroup libvlc LibVLC
+ * LibVLC is the external programming interface of the VLC media player.
+ * It is used to embed VLC into other applications or frameworks.
  * @{
  */
 
@@ -61,12 +61,19 @@ extern "C" {
 #include <stdarg.h>
 #include <vlc/libvlc_structures.h>
 
-/*****************************************************************************
- * Error handling
- *****************************************************************************/
-/** \defgroup libvlc_error libvlc_error
- * \ingroup libvlc_core
- * LibVLC error handling
+/** \defgroup libvlc_core LibVLC core
+ * \ingroup libvlc
+ * Before it can do anything useful, LibVLC must be initialized.
+ * You can create one (or more) instance(s) of LibVLC in a given process,
+ * with libvlc_new() and destroy them with libvlc_release().
+ *
+ * \version This documents LibVLC version 1.1.
+ * Earlier versions (0.9 and 1.0) are <b>not</b> compatible.
+ * @{
+ */
+
+/** \defgroup libvlc_error LibVLC error handling
+ * \ingroup libvlc_error
  * @{
  */
 
@@ -103,17 +110,6 @@ const char *libvlc_printerr (const char *fmt, ...);
 
 /**@} */
 
-
-/*****************************************************************************
- * Core handling
- *****************************************************************************/
-
-/** \defgroup libvlc_core libvlc_core
- * \ingroup libvlc
- * LibVLC Core
- * @{
- */
-
 /**
  * Create and initialize a libvlc instance.
  *
@@ -162,7 +158,7 @@ void libvlc_wait( libvlc_instance_t *p_instance );
 /**
  * Retrieve libvlc version.
  *
- * Example: "0.9.0-git Grishenko"
+ * Example: "1.1.0-git The Luggage"
  *
  * \return a string containing the libvlc version
  */
@@ -186,17 +182,15 @@ VLC_PUBLIC_API const char * libvlc_get_compiler(void);
  */
 VLC_PUBLIC_API const char * libvlc_get_changeset(void);
 
-struct vlc_object_t;
-
-/** @}*/
-
-/*****************************************************************************
- * Event handling
- *****************************************************************************/
 
-/** \defgroup libvlc_event libvlc_event
- * \ingroup libvlc_core
- * LibVLC Events
+/** \defgroup libvlc_event LibVLC asynchronous events
+ * LibVLC emits asynchronous events.
+ *
+ * Several LibVLC objects (such @ref libvlc_instance_t as
+ * @ref libvlc_media_player_t) generate events asynchronously. Each of them
+ * provides @ref libvlc_event_manager_t event manager. You can subscribe to
+ * events with libvlc_event_attach() and unsubscribe with
+ * libvlc_event_detach().
  * @{
  */
 
@@ -204,17 +198,20 @@ struct vlc_object_t;
  * Event manager that belongs to a libvlc object, and from whom events can
  * be received.
  */
-
 typedef struct libvlc_event_manager_t libvlc_event_manager_t;
-typedef struct libvlc_event_t libvlc_event_t;
-typedef uint32_t libvlc_event_type_t;
-    
+
+struct libvlc_event_t;
+
+/**
+ * Type of a LibVLC event.
+ */
+typedef int libvlc_event_type_t;
+
 /**
  * Callback function notification
  * \param p_event the event triggering the callback
  */
-
-typedef void ( *libvlc_callback_t )( const libvlc_event_t *, void * );
+typedef void ( *libvlc_callback_t )( const struct libvlc_event_t *, void * );
     
 /**
  * Register for an event notification.
@@ -245,22 +242,11 @@ VLC_PUBLIC_API void libvlc_event_detach( libvlc_event_manager_t *p_event_manager
                                          libvlc_callback_t f_callback,
                                          void *p_user_data );
 
-/**
- * Get an event's type name.
- *
- * \param event_type the desired event
- */
-VLC_PUBLIC_API const char * libvlc_event_type_name( libvlc_event_type_t event_type );
-
 /** @} */
 
-/*****************************************************************************
- * Message log handling
- *****************************************************************************/
-
-/** \defgroup libvlc_log libvlc_log
- * \ingroup libvlc_core
- * LibVLC Message Logging
+/** \defgroup libvlc_log LibVLC logging
+ * libvlc_log_* functions provide access to the LibVLC messages log.
+ * This is used for debugging or by advanced users.
  * @{
  */
 
@@ -349,11 +335,11 @@ VLC_PUBLIC_API libvlc_log_message_t *libvlc_log_iterator_next( libvlc_log_iterat
                                                                libvlc_log_message_t *p_buffer );
 
 /** @} */
+/** @} */
+/** @} */
 
 # ifdef __cplusplus
 }
 # endif
 
 #endif /* <vlc/libvlc.h> */
-
-/** @} */

include/vlc/libvlc_events.h

@@ -34,105 +34,85 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * Events handling
- *****************************************************************************/
-
-/** \defgroup libvlc_event libvlc_event
- * \ingroup libvlc_core
- * LibVLC Available Events
+/**
+ * \ingroup libvlc_event
  * @{
  */
 
+/**
+ * Event types
+ */
+enum libvlc_event_e {
     /* Append new event types at the end. Do not remove, insert or
      * re-order any entry. The cpp will prepend libvlc_ to the symbols. */
-#define DEFINE_LIBVLC_EVENT_TYPES \
-    DEF( MediaMetaChanged ), \
-    DEF( MediaSubItemAdded ), \
-    DEF( MediaDurationChanged ), \
-    DEF( MediaPreparsedChanged ), \
-    DEF( MediaFreed ), \
-    DEF( MediaStateChanged ), \
-    \
-    DEF( MediaPlayerNothingSpecial ), \
-    DEF( MediaPlayerOpening ), \
-    DEF( MediaPlayerBuffering ), \
-    DEF( MediaPlayerPlaying ), \
-    DEF( MediaPlayerPaused ), \
-    DEF( MediaPlayerStopped ), \
-    DEF( MediaPlayerForward ), \
-    DEF( MediaPlayerBackward ), \
-    DEF( MediaPlayerEndReached ), \
-    DEF( MediaPlayerEncounteredError ), \
-    DEF( MediaPlayerTimeChanged ), \
-    DEF( MediaPlayerPositionChanged ), \
-    DEF( MediaPlayerSeekableChanged ), \
-    DEF( MediaPlayerPausableChanged ), \
-    \
-    DEF( MediaListItemAdded ), \
-    DEF( MediaListWillAddItem ), \
-    DEF( MediaListItemDeleted ), \
-    DEF( MediaListWillDeleteItem ), \
-    \
-    DEF( MediaListViewItemAdded ), \
-    DEF( MediaListViewWillAddItem ), \
-    DEF( MediaListViewItemDeleted ), \
-    DEF( MediaListViewWillDeleteItem ), \
-    \
-    DEF( MediaListPlayerPlayed ), \
-    DEF( MediaListPlayerNextItemSet ), \
-    DEF( MediaListPlayerStopped ), \
-    \
-    DEF( MediaDiscovererStarted ), \
-    DEF( MediaDiscovererEnded ), \
-    \
-    DEF( MediaPlayerTitleChanged ), \
-    DEF( MediaPlayerSnapshotTaken ), \
-    DEF( MediaPlayerLengthChanged ), \
-    \
-    DEF( VlmMediaAdded ), \
-    DEF( VlmMediaRemoved ), \
-    DEF( VlmMediaChanged ), \
-    DEF( VlmMediaInstanceStarted ), \
-    DEF( VlmMediaInstanceStopped ), \
-    DEF( VlmMediaInstanceStatusInit ), \
-    DEF( VlmMediaInstanceStatusOpening ), \
-    DEF( VlmMediaInstanceStatusPlaying ), \
-    DEF( VlmMediaInstanceStatusPause ), \
-    DEF( VlmMediaInstanceStatusEnd ), \
-    DEF( VlmMediaInstanceStatusError ), \
-    \
-    DEF( MediaPlayerMediaChanged ), \
-/* New event types HERE */
-
-#ifdef __cplusplus
-enum libvlc_event_type_e {
-#else
-enum libvlc_event_type_t {
-#endif
-#define DEF(a) libvlc_##a
-    DEFINE_LIBVLC_EVENT_TYPES
+    libvlc_MediaMetaChanged,
+    libvlc_MediaSubItemAdded,
+    libvlc_MediaDurationChanged,
+    libvlc_MediaPreparsedChanged,
+    libvlc_MediaFreed,
+    libvlc_MediaStateChanged,
+
+    libvlc_MediaPlayerNothingSpecial,
+    libvlc_MediaPlayerOpening,
+    libvlc_MediaPlayerBuffering,
+    libvlc_MediaPlayerPlaying,
+    libvlc_MediaPlayerPaused,
+    libvlc_MediaPlayerStopped,
+    libvlc_MediaPlayerForward,
+    libvlc_MediaPlayerBackward,
+    libvlc_MediaPlayerEndReached,
+    libvlc_MediaPlayerEncounteredError,
+    libvlc_MediaPlayerTimeChanged,
+    libvlc_MediaPlayerPositionChanged,
+    libvlc_MediaPlayerSeekableChanged,
+    libvlc_MediaPlayerPausableChanged,
+
+    libvlc_MediaListItemAdded,
+    libvlc_MediaListWillAddItem,
+    libvlc_MediaListItemDeleted,
+    libvlc_MediaListWillDeleteItem,
+
+    libvlc_MediaListViewItemAdded,
+    libvlc_MediaListViewWillAddItem,
+    libvlc_MediaListViewItemDeleted,
+    libvlc_MediaListViewWillDeleteItem,
+
+    libvlc_MediaListPlayerPlayed,
+    libvlc_MediaListPlayerNextItemSet,
+    libvlc_MediaListPlayerStopped,
+
+    libvlc_MediaDiscovererStarted,
+    libvlc_MediaDiscovererEnded,
+
+    libvlc_MediaPlayerTitleChanged,
+    libvlc_MediaPlayerSnapshotTaken,
+    libvlc_MediaPlayerLengthChanged,
+
+    libvlc_VlmMediaAdded,
+    libvlc_VlmMediaRemoved,
+    libvlc_VlmMediaChanged,
+    libvlc_VlmMediaInstanceStarted,
+    libvlc_VlmMediaInstanceStopped,
+    libvlc_VlmMediaInstanceStatusInit,
+    libvlc_VlmMediaInstanceStatusOpening,
+    libvlc_VlmMediaInstanceStatusPlaying,
+    libvlc_VlmMediaInstanceStatusPause,
+    libvlc_VlmMediaInstanceStatusEnd,
+    libvlc_VlmMediaInstanceStatusError,
+
+    libvlc_MediaPlayerMediaChanged,
+    /* New event types HERE */
     libvlc_num_event_types
-#undef  DEF
 };
 
-/* Implementing libvlc_event_type_name() needs the definition too. */
-#ifndef LIBVLC_EVENT_TYPES_KEEP_DEFINE
-#undef  DEFINE_LIBVLC_EVENT_TYPES
-#endif
-
 /**
- * An Event
- * \param type the even type
- * \param p_obj the sender object
- * \param u Event dependent content
+ * A LibVLC event
  */
-
-struct libvlc_event_t
+typedef struct libvlc_event_t
 {
-    libvlc_event_type_t type;
-    void * p_obj;
-    union event_type_specific
+    int   type; /**< Event type (see @ref libvlc_event_e) */
+    void *p_obj; /**< Object emitting the event */
+    union
     {
         /* media descriptor */
         struct
@@ -234,8 +214,8 @@ struct libvlc_event_t
         {
             libvlc_media_t * new_media;
         } media_player_media_changed;
-    } u;
-};
+    } u; /**< Type-dependent event description */
+} libvlc_event_t;
 
 
 /**@} */

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,
@@ -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

include/vlc/libvlc_media_discoverer.h

@@ -35,12 +35,13 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * Services/Media Discovery
- *****************************************************************************/
-/** \defgroup libvlc_media_discoverer libvlc_media_discoverer
+/** \defgroup libvlc_media_discoverer LibVLC media discovery
  * \ingroup libvlc
- * LibVLC Media Discoverer
+ * LibVLC media discovery finds available media via various means.
+ * This corresponds to the service discovery functionality in VLC media player.
+ * Different plugins find potential medias locally (e.g. user media directory),
+ * from peripherals (e.g. video capture device), on the local network
+ * (e.g. SAP) or on the Internet (e.g. Internet radios).
  * @{
  */
 

include/vlc/libvlc_media_library.h

@@ -35,12 +35,8 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * Media Library
- *****************************************************************************/
-/** \defgroup libvlc_media_library libvlc_media_library
+/** \defgroup libvlc_media_library LibVLC media library
  * \ingroup libvlc
- * LibVLC Media Library
  * @{
  */
 

include/vlc/libvlc_media_list.h

@@ -33,12 +33,9 @@
 extern "C" {
 # endif
 
-/*****************************************************************************
- * Media List
- *****************************************************************************/
-/** \defgroup libvlc_media_list libvlc_media_list
+/** \defgroup libvlc_media_list LibVLC media list
  * \ingroup libvlc
- * LibVLC Media List, a media list holds multiple media descriptors
+ * A LibVLC media list holds multiple @ref libvlc_media_t media descriptors.
  * @{
  */
 

include/vlc/libvlc_media_list_player.h

@@ -36,10 +36,13 @@ extern "C" {
 /*****************************************************************************
  * Media List Player
  *****************************************************************************/
-/** \defgroup libvlc_media_list_player libvlc_media_list_player
+/** \defgroup libvlc_media_list_player LibVLC media list player
  * \ingroup libvlc
- * LibVLC Media List Player, play a media_list. You can see that as a media
- * instance subclass
+ * The LibVLC media list player plays a @ref libvlc_media_list_t list of media,
+ * in a certain order.
+ * This is required to especially support playlist files.
+ * The normal @ref libvlc_media_player_t LibVLC media player can only play a
+ * single media, and does not handle playlist files properly.
  * @{
  */
 

include/vlc/libvlc_media_player.h

@@ -38,10 +38,9 @@ extern "C" {
 /*****************************************************************************
  * Media Player
  *****************************************************************************/
-/** \defgroup libvlc_media_player libvlc_media_player
+/** \defgroup libvlc_media_player LibVLC media player
  * \ingroup libvlc
- * LibVLC Media Player, object that let you play a media
- * in a custom drawable
+ * A LibVLC media player plays one media (usually in a custom drawable).
  * @{
  */
 
@@ -197,10 +196,12 @@ VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi );
  * The object minimal_macosx expects is of kind NSObject and should
  * respect the protocol:
  *
- * @protocol VLCOpenGLVideoViewEmbedding <NSObject>
+ * @begincode
+ * \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
  * - (void)addVoutSubview:(NSView *)view;
  * - (void)removeVoutSubview:(NSView *)view;
- * @end
+ * \@end
+ * @endcode
  *
  * You can find a live example in VLCVideoView in VLCKit.framework.
  *
@@ -484,9 +485,7 @@ VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi
  */
 VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
 
-/** \defgroup libvlc_video libvlc_video
- * \ingroup libvlc_media_player
- * LibVLC Video handling
+/** \defgroup libvlc_video LibVLC video controls
  * @{
  */
 
@@ -909,9 +908,7 @@ VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
 
 /** @} video */
 
-/** \defgroup libvlc_audio libvlc_audio
- * \ingroup libvlc_media_player
- * LibVLC Audio handling
+/** \defgroup libvlc_audio LibVLC audio controls
  * @{
  */
 

include/vlc/libvlc_vlm.h

@@ -37,9 +37,8 @@ extern "C" {
 /*****************************************************************************
  * VLM
  *****************************************************************************/
-/** \defgroup libvlc_vlm libvlc_vlm
+/** \defgroup libvlc_vlm LibVLC VLM
  * \ingroup libvlc
- * LibVLC VLM
  * @{
  */
 

src/control/event.c

@@ -240,27 +240,6 @@ void libvlc_event_send( libvlc_event_manager_t * p_em,
  * Public libvlc functions
  */
 
-/**************************************************************************
- *       libvlc_event_type_name (public) :
- *
- * Get the char * name of an event type.
- **************************************************************************/
-static const char event_type_to_name[][libvlc_num_event_types] =
-{
-#define DEF(a) [libvlc_##a]=#a
-    DEFINE_LIBVLC_EVENT_TYPES
-#undef  DEF
-};
-
-static const char unknown_event_name[] = "Unknown Event";
-
-const char * libvlc_event_type_name( libvlc_event_type_t event_type )
-{
-    if( event_type >= libvlc_num_event_types )
-        return unknown_event_name;
-    return event_type_to_name[event_type];
-}
-
 /**************************************************************************
  *       event_attach (internal) :
  *
@@ -299,8 +278,7 @@ int event_attach( libvlc_event_manager_t * p_event_manager,
     vlc_mutex_unlock( &p_event_manager->object_lock );
     
     free(listener);
-    fprintf( stderr, "This object event manager doesn't know about '%s' events",
-             libvlc_event_type_name(event_type) );
+    fprintf( stderr, "Unknown event type %d", event_type );
     assert(0);
     return -1;
 }

src/libvlc.sym

@@ -29,7 +29,6 @@ libvlc_event_manager_new
 libvlc_event_manager_register_event_type
 libvlc_event_manager_release
 libvlc_event_send
-libvlc_event_type_name
 libvlc_get_changeset
 libvlc_get_compiler
 libvlc_get_fullscreen