From: Rémi Denis-Courmont Date: Sat, 20 Feb 2010 11:04:33 +0000 (+0200) Subject: Improve Doxygen documentation, deobfuscate event types X-Git-Tag: 1.1.0-pre1~823 X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=fd3ef9055df9088e6c1fd544a9d26a71f465d0cb;p=vlc Improve Doxygen documentation, deobfuscate event types --- diff --git a/include/vlc/deprecated.h b/include/vlc/deprecated.h index 16406f3451..216b1caba4 100644 --- a/include/vlc/deprecated.h +++ b/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. * @{ */ diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h index 51bb78f4c2..4ccbfeb238 100644 --- a/include/vlc/libvlc.h +++ b/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 #include -/***************************************************************************** - * 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 not 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 /* */ - -/** @} */ diff --git a/include/vlc/libvlc_events.h b/include/vlc/libvlc_events.h index afb4064b99..02278e4e09 100644 --- a/include/vlc/libvlc_events.h +++ b/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; /**@} */ diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h index a2222864c9..075a1c670f 100644 --- 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, @@ -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 diff --git a/include/vlc/libvlc_media_discoverer.h b/include/vlc/libvlc_media_discoverer.h index f6aee418cb..2552d6b39b 100644 --- a/include/vlc/libvlc_media_discoverer.h +++ b/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). * @{ */ diff --git a/include/vlc/libvlc_media_library.h b/include/vlc/libvlc_media_library.h index 570f9a7c38..76b5b161e6 100644 --- a/include/vlc/libvlc_media_library.h +++ b/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 * @{ */ diff --git a/include/vlc/libvlc_media_list.h b/include/vlc/libvlc_media_list.h index 23cfeae13b..32304ee430 100644 --- a/include/vlc/libvlc_media_list.h +++ b/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. * @{ */ diff --git a/include/vlc/libvlc_media_list_player.h b/include/vlc/libvlc_media_list_player.h index e8d39aafde..3a1f913b6a 100644 --- a/include/vlc/libvlc_media_list_player.h +++ b/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. * @{ */ diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index 3ae7873031..3bbb6b9b48 100644 --- a/include/vlc/libvlc_media_player.h +++ b/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 + * @begincode + * \@protocol VLCOpenGLVideoViewEmbedding * - (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 * @{ */ diff --git a/include/vlc/libvlc_vlm.h b/include/vlc/libvlc_vlm.h index 016d20745c..f09dbe506e 100644 --- a/include/vlc/libvlc_vlm.h +++ b/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 * @{ */ diff --git a/src/control/event.c b/src/control/event.c index af3f043c9a..2fb9c35ca0 100644 --- a/src/control/event.c +++ b/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; } diff --git a/src/libvlc.sym b/src/libvlc.sym index b38ec01755..ac3a64d9af 100644 --- a/src/libvlc.sym +++ b/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