From 4ee1038059ee6c7e7225a5a0e2ed1643d49e46fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Denis-Courmont?= Date: Sun, 14 Jun 2015 19:00:16 +0300 Subject: [PATCH] include: improve Doxygen modules In particular, move \file stanzas inside groups. --- include/vlc/deprecated.h | 10 ++-------- include/vlc/libvlc.h | 7 ++----- include/vlc/libvlc_media.h | 7 ++----- include/vlc/libvlc_media_discoverer.h | 7 ++----- include/vlc/libvlc_media_library.h | 7 ++----- include/vlc/libvlc_media_list.h | 7 ++----- include/vlc/libvlc_media_list_player.h | 10 ++-------- include/vlc/libvlc_media_player.h | 10 ++-------- include/vlc/libvlc_vlm.h | 11 ++--------- include/vlc_access.h | 9 ++++----- include/vlc_codec.h | 25 +++++++++++++------------ include/vlc_demux.h | 11 +++++------ include/vlc_es_out.h | 10 ++++------ include/vlc_filter.h | 5 ++++- include/vlc_input.h | 7 +++++-- include/vlc_interface.h | 10 +++------- include/vlc_memory.h | 7 ++----- include/vlc_messages.h | 14 ++++++-------- include/vlc_objects.h | 9 +++------ include/vlc_playlist.h | 14 ++++++-------- include/vlc_stream.h | 12 ++++-------- include/vlc_strings.h | 9 +++------ include/vlc_subpicture.h | 8 ++++---- include/vlc_update.h | 9 +++------ include/vlc_variables.h | 13 ++++--------- include/vlc_vlm.h | 9 ++++----- include/vlc_vod.h | 11 ++++------- include/vlc_vout.h | 15 +++++---------- src/playlist/playlist_internal.h | 15 +++++---------- 29 files changed, 109 insertions(+), 189 deletions(-) diff --git a/include/vlc/deprecated.h b/include/vlc/deprecated.h index 7f55090fcd..fdda1e21be 100644 --- a/include/vlc/deprecated.h +++ b/include/vlc/deprecated.h @@ -25,22 +25,16 @@ #ifndef LIBVLC_DEPRECATED_H #define LIBVLC_DEPRECATED_H 1 -/** - * \file - * This file defines libvlc deprecated API - */ - # ifdef __cplusplus extern "C" { # endif -/***************************************************************************** - * Playlist (Deprecated) - *****************************************************************************/ /** \defgroup libvlc_playlist LibVLC playlist (legacy) * \ingroup libvlc * @deprecated Use @ref libvlc_media_list instead. * @{ + * \file + * LibVLC deprecated playlist API */ /** diff --git a/include/vlc/libvlc.h b/include/vlc/libvlc.h index 2cb8b395a2..7b01203bb4 100644 --- a/include/vlc/libvlc.h +++ b/include/vlc/libvlc.h @@ -23,16 +23,13 @@ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -/** - * \file - * This file defines libvlc external API - */ - /** * \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. * @{ + * \file + * LibVLC core external API */ #ifndef VLC_LIBVLC_H diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h index 9b16526b0b..641f134bcb 100644 --- a/include/vlc/libvlc_media.h +++ b/include/vlc/libvlc_media.h @@ -23,11 +23,6 @@ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -/** - * \file - * This file defines libvlc_media external API - */ - #ifndef VLC_LIBVLC_MEDIA_H #define VLC_LIBVLC_MEDIA_H 1 @@ -40,6 +35,8 @@ extern "C" { * @ref libvlc_media_t is an abstract representation of a playable media. * It consists of a media location and various optional meta data. * @{ + * \file + * LibVLC media item/descriptor external API */ typedef struct libvlc_media_t libvlc_media_t; diff --git a/include/vlc/libvlc_media_discoverer.h b/include/vlc/libvlc_media_discoverer.h index 26268025e8..886660765d 100644 --- a/include/vlc/libvlc_media_discoverer.h +++ b/include/vlc/libvlc_media_discoverer.h @@ -23,11 +23,6 @@ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -/** - * \file - * This file defines libvlc_media_discoverer external API - */ - #ifndef VLC_LIBVLC_MEDIA_DISCOVERER_H #define VLC_LIBVLC_MEDIA_DISCOVERER_H 1 @@ -43,6 +38,8 @@ extern "C" { * from peripherals (e.g. video capture device), on the local network * (e.g. SAP) or on the Internet (e.g. Internet radios). * @{ + * \file + * LibVLC media discovery external API */ typedef struct libvlc_media_discoverer_t libvlc_media_discoverer_t; diff --git a/include/vlc/libvlc_media_library.h b/include/vlc/libvlc_media_library.h index fa7094a6a8..facbf813aa 100644 --- a/include/vlc/libvlc_media_library.h +++ b/include/vlc/libvlc_media_library.h @@ -23,11 +23,6 @@ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -/** - * \file - * This file defines libvlc_media_library external API - */ - #ifndef VLC_LIBVLC_MEDIA_LIBRARY_H #define VLC_LIBVLC_MEDIA_LIBRARY_H 1 @@ -38,6 +33,8 @@ extern "C" { /** \defgroup libvlc_media_library LibVLC media library * \ingroup libvlc * @{ + * \file + * LibVLC media library external API */ typedef struct libvlc_media_library_t libvlc_media_library_t; diff --git a/include/vlc/libvlc_media_list.h b/include/vlc/libvlc_media_list.h index 015824bf54..dfb67a6173 100644 --- a/include/vlc/libvlc_media_list.h +++ b/include/vlc/libvlc_media_list.h @@ -24,11 +24,6 @@ #ifndef LIBVLC_MEDIA_LIST_H #define LIBVLC_MEDIA_LIST_H 1 -/** - * \file - * This file defines libvlc_media_list API - */ - # ifdef __cplusplus extern "C" { # endif @@ -37,6 +32,8 @@ extern "C" { * \ingroup libvlc * A LibVLC media list holds multiple @ref libvlc_media_t media descriptors. * @{ + * \file + * LibVLC media list (playlist) external API */ typedef struct libvlc_media_list_t libvlc_media_list_t; diff --git a/include/vlc/libvlc_media_list_player.h b/include/vlc/libvlc_media_list_player.h index c95ad972c7..b85981d4ed 100644 --- a/include/vlc/libvlc_media_list_player.h +++ b/include/vlc/libvlc_media_list_player.h @@ -24,18 +24,10 @@ #ifndef LIBVLC_MEDIA_LIST_PLAYER_H #define LIBVLC_MEDIA_LIST_PLAYER_H 1 -/** - * \file - * This file defines libvlc_media_list_player API - */ - # ifdef __cplusplus extern "C" { # endif -/***************************************************************************** - * Media List Player - *****************************************************************************/ /** \defgroup libvlc_media_list_player LibVLC media list player * \ingroup libvlc * The LibVLC media list player plays a @ref libvlc_media_list_t list of media, @@ -44,6 +36,8 @@ extern "C" { * The normal @ref libvlc_media_player_t LibVLC media player can only play a * single media, and does not handle playlist files properly. * @{ + * \file + * LibVLC media list player external API */ typedef struct libvlc_media_list_player_t libvlc_media_list_player_t; diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index 6ed1ddb509..ca32d1a2c5 100644 --- a/include/vlc/libvlc_media_player.h +++ b/include/vlc/libvlc_media_player.h @@ -23,11 +23,6 @@ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -/** - * \file - * This file defines libvlc_media_player external API - */ - #ifndef VLC_LIBVLC_MEDIA_PLAYER_H #define VLC_LIBVLC_MEDIA_PLAYER_H 1 @@ -37,13 +32,12 @@ extern "C" { # include # endif -/***************************************************************************** - * Media Player - *****************************************************************************/ /** \defgroup libvlc_media_player LibVLC media player * \ingroup libvlc * A LibVLC media player plays one media (usually in a custom drawable). * @{ + * \file + * LibVLC simple media player external API */ typedef struct libvlc_media_player_t libvlc_media_player_t; diff --git a/include/vlc/libvlc_vlm.h b/include/vlc/libvlc_vlm.h index 26e5cbb5ee..a4f335dd68 100644 --- a/include/vlc/libvlc_vlm.h +++ b/include/vlc/libvlc_vlm.h @@ -25,24 +25,17 @@ #ifndef LIBVLC_VLM_H #define LIBVLC_VLM_H 1 -/** - * \file - * This file defines libvlc_vlm_* external API - */ - # ifdef __cplusplus extern "C" { # endif -/***************************************************************************** - * VLM - *****************************************************************************/ /** \defgroup libvlc_vlm LibVLC VLM * \ingroup libvlc * @{ + * \file + * LibVLC stream output manager external API */ - /** * Release the vlm instance related to the given libvlc_instance_t * diff --git a/include/vlc_access.h b/include/vlc_access.h index 93b3b7cb8e..fe5eacf1bf 100644 --- a/include/vlc_access.h +++ b/include/vlc_access.h @@ -24,16 +24,15 @@ #ifndef VLC_ACCESS_H #define VLC_ACCESS_H 1 -/** - * \file - * This file defines functions and definitions for access object - */ - #include /** * \defgroup access Access + * \ingroup input + * Raw input byte streams * @{ + * \file + * Input byte stream modules interface */ enum access_query_e diff --git a/include/vlc_codec.h b/include/vlc_codec.h index 8f6f46a321..aebcf4cd44 100644 --- a/include/vlc_codec.h +++ b/include/vlc_codec.h @@ -29,18 +29,17 @@ #include #include -/** - * \file - * This file defines the structure and types used by decoders and encoders - */ - typedef struct decoder_owner_sys_t decoder_owner_sys_t; /** - * \defgroup decoder Decoder - * - * The structure describing a decoder + * \defgroup codec Codec + * Decoders and encoders + * @{ + * \file + * Decoder and encoder modules interface * + * \defgroup decoder Decoder + * Audio, video and text decoders * @{ */ @@ -136,9 +135,7 @@ struct decoder_t /** * \defgroup encoder Encoder - * - * The structure describing a Encoder - * + * Audio, video and text encoders * @{ */ @@ -172,9 +169,11 @@ struct encoder_t /** * @} + * + * \ingroup decoder + * @{ */ - /** * This function notifies the video output pipeline of a new video output * format (fmt_out.video). If there is currently no video output or if the @@ -242,4 +241,6 @@ VLC_API mtime_t decoder_GetDisplayDate( decoder_t *, mtime_t ) VLC_USED; */ VLC_API int decoder_GetDisplayRate( decoder_t * ) VLC_USED; +/** @} */ +/** @} */ #endif /* _VLC_CODEC_H */ diff --git a/include/vlc_demux.h b/include/vlc_demux.h index 93197ad3bd..fb83d66f81 100644 --- a/include/vlc_demux.h +++ b/include/vlc_demux.h @@ -24,18 +24,17 @@ #ifndef VLC_DEMUX_H #define VLC_DEMUX_H 1 -/** - * \file - * This files defines functions and structures used by demux objects in vlc - */ - #include #include #include /** - * \defgroup demux Demux + * \defgroup demux Demultiplexer + * \ingroup input + * Demultiplexers (file format parsers) * @{ + * \file + * Demultiplexer modules interface */ struct demux_t diff --git a/include/vlc_es_out.h b/include/vlc_es_out.h index cf1abcec08..aa6b427354 100644 --- a/include/vlc_es_out.h +++ b/include/vlc_es_out.h @@ -25,13 +25,11 @@ #define VLC_ES_OUT_H 1 /** - * \file - * This file defines functions and structures for handling es_out in stream output - */ - -/** - * \defgroup es out Es Out + * \defgroup es_out ES output + * Elementary streams output * @{ + * \file + * Elementary streams output interface */ enum es_out_query_e diff --git a/include/vlc_filter.h b/include/vlc_filter.h index 8e023614a2..7b27877b59 100644 --- a/include/vlc_filter.h +++ b/include/vlc_filter.h @@ -31,8 +31,11 @@ #include /** + * \defgroup filter Filters + * Audio, video, text filters + * @{ * \file - * This file defines the structure and types used by video and audio filters + * Filter modules interface */ typedef struct filter_owner_sys_t filter_owner_sys_t; diff --git a/include/vlc_input.h b/include/vlc_input.h index 7ae07b147a..21b8d1c9e3 100644 --- a/include/vlc_input.h +++ b/include/vlc_input.h @@ -22,13 +22,15 @@ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. *****************************************************************************/ -/* __ is need because conflict with */ #ifndef VLC_INPUT_H #define VLC_INPUT_H 1 /** + * \defgroup input Input + * Input thread + * @{ * \file - * This file defines functions, structures and enums for input objects in vlc + * Input thread interface */ #include @@ -671,4 +673,5 @@ VLC_API void input_resource_PutAout( input_resource_t *, audio_output_t * ); */ VLC_API void input_resource_ResetAout( input_resource_t * ); +/** @} */ #endif diff --git a/include/vlc_interface.h b/include/vlc_interface.h index ca1c5646b3..5386269016 100644 --- a/include/vlc_interface.h +++ b/include/vlc_interface.h @@ -32,16 +32,12 @@ extern "C" { typedef struct intf_dialog_args_t intf_dialog_args_t; -/** - * \file - * This file contains structures and function prototypes for - * interface management in vlc - */ - /** * \defgroup vlc_interface Interface - * These functions and structures are for interface management + * VLC user interfaces * @{ + * \file + * VLC user interface modules */ typedef struct intf_sys_t intf_sys_t; diff --git a/include/vlc_memory.h b/include/vlc_memory.h index f4b8d4931b..22ea0ea385 100644 --- a/include/vlc_memory.h +++ b/include/vlc_memory.h @@ -25,14 +25,11 @@ #include -/** - * \file - * This file deals with memory fixups - */ - /** * \defgroup memory Memory * @{ + * \file + * Memory fixups */ /** diff --git a/include/vlc_messages.h b/include/vlc_messages.h index 2da692e65c..da5fc8fafb 100644 --- a/include/vlc_messages.h +++ b/include/vlc_messages.h @@ -27,19 +27,17 @@ #ifndef VLC_MESSAGES_H_ #define VLC_MESSAGES_H_ -/** - * \file - * This file defines structures and functions to handle messages and statistics gathering - */ - #include /** - * \defgroup messages Messages - * This library provides basic functions for threads to interact with user - * interface, such as message output. + * \defgroup messages Logging + * \brief Message logs + * + * Functions for modules to emit log messages. * * @{ + * \file + * Logging functions */ /** Message types */ diff --git a/include/vlc_objects.h b/include/vlc_objects.h index 7ccf568f48..8fa13fe401 100644 --- a/include/vlc_objects.h +++ b/include/vlc_objects.h @@ -22,13 +22,10 @@ *****************************************************************************/ /** - * \file - * This file defines the vlc_object_t structure and object types. - */ - -/** - * \defgroup vlc_object Objects + * \defgroup vlc_object VLC objects * @{ + * \file + * Common VLC object defintions */ /* Object flags */ diff --git a/include/vlc_playlist.h b/include/vlc_playlist.h index 947b2c613b..141a54cc36 100644 --- a/include/vlc_playlist.h +++ b/include/vlc_playlist.h @@ -35,11 +35,11 @@ TYPEDEF_ARRAY(playlist_item_t*, playlist_item_array_t) struct intf_thread_t; /** + * \defgroup vlc_playlist VLC playlist + * VLC playlist controls + * @{ * \file - * This file contain structures and function prototypes related - * to the playlist in vlc - * - * \defgroup vlc_playlist Playlist + * VLC playlist control interface * * The VLC playlist system has a tree structure. This allows advanced * categorization, like for SAP streams (which are grouped by "sap groups"). @@ -115,10 +115,8 @@ struct intf_thread_t; * The playlist contains rate-variable which is propagated to current input if available * also rate-slower/rate-faster is in use * - * XXX Be really carefull, playlist_item_t->i_id and input_item_t->i_id are not - * the same. Yes, the situation is pretty bad. - * - * @{ + * \warning Be really carefull, playlist_item_t->i_id and input_item_t->i_id + * are not the same. Yes, the situation is pretty bad. */ /** Helper structure to export to file part of the playlist */ diff --git a/include/vlc_stream.h b/include/vlc_stream.h index dda58ceb4a..be44c4ce45 100644 --- a/include/vlc_stream.h +++ b/include/vlc_stream.h @@ -26,20 +26,16 @@ #include -/** - * \file - * This file defines structures and functions for stream (between access and demux) descriptor in vlc - */ - # ifdef __cplusplus extern "C" { # endif /** * \defgroup stream Stream - * - * This will allow you to easily handle read/seek in demuxer modules. - * @{ + * \ingroup input + * Buffered input byte streams + * \file + * Byte streams and byte stream filter modules interface */ /* Opaque definition for text reader context */ diff --git a/include/vlc_strings.h b/include/vlc_strings.h index 2170c240eb..0ab3c5badc 100644 --- a/include/vlc_strings.h +++ b/include/vlc_strings.h @@ -25,13 +25,10 @@ #define VLC_STRINGS_H 1 /** - * \file - * This file defines functions and structures handling misc strings - */ - -/** - * \defgroup strings Strings + * \defgroup strings String helpers * @{ + * \file + * Helper functions for nul-terminated strings */ static inline int vlc_ascii_toupper( int c ) diff --git a/include/vlc_subpicture.h b/include/vlc_subpicture.h index 6bfede1710..dc977f6821 100644 --- a/include/vlc_subpicture.h +++ b/include/vlc_subpicture.h @@ -27,19 +27,19 @@ #define VLC_SUBPICTURE_H 1 /** - * \file - * This file defines subpicture structures and functions in vlc */ #include #include /** - * \defgroup subpicture Video Subpictures + * \defgroup subpicture Video sub-pictures + * \ingroup video_output * Subpictures are pictures that should be displayed on top of the video, like * subtitles and OSD - * \ingroup video_output * @{ + * \file + * Subpictures functions */ /** diff --git a/include/vlc_update.h b/include/vlc_update.h index f7592212e7..e84c92757e 100644 --- a/include/vlc_update.h +++ b/include/vlc_update.h @@ -26,13 +26,10 @@ #define VLC_UPDATE_H /** + * \defgroup update Software updates + * Over-the-air VLC software updates * \file - * This file defines update API in vlc - */ - -/** - * \defgroup update Update - * + *VLC software update interface * @{ */ diff --git a/include/vlc_variables.h b/include/vlc_variables.h index bbb6197af8..d855c30691 100644 --- a/include/vlc_variables.h +++ b/include/vlc_variables.h @@ -25,20 +25,15 @@ #ifndef VLC_VARIABLES_H #define VLC_VARIABLES_H 1 -/** - * \file - * This file defines functions and structures for dynamic variables in vlc - */ - /** * \defgroup variables Variables + * \ingroup vlc_object * - * Functions for using the object variables in vlc. - * - * Vlc have a very powerful "object variable" infrastructure useful - * for many things. + * VLC object variables and callbacks * * @{ + * \file + * VLC object variables and callbacks interface */ #define VLC_VAR_TYPE 0x00ff diff --git a/include/vlc_vlm.h b/include/vlc_vlm.h index 11111da6ed..88d4437cc1 100644 --- a/include/vlc_vlm.h +++ b/include/vlc_vlm.h @@ -25,19 +25,18 @@ #ifndef VLC_VLM_H #define VLC_VLM_H 1 -/** - * \file - * This file defines VLM core functions and structures in vlc - */ - #include /** * \defgroup server VLM + * VLC stream manager + * * VLM is the server core in vlc that allows streaming of multiple media streams * at the same time. It provides broadcast, schedule and video on demand features * for streaming using several streaming and network protocols. * @{ + * \file + * VLC stream manager interface */ /** VLM media */ diff --git a/include/vlc_vod.h b/include/vlc_vod.h index 2f094338a9..382108acf1 100644 --- a/include/vlc_vod.h +++ b/include/vlc_vod.h @@ -25,15 +25,12 @@ #define VLC_VOD_H 1 /** - * \file - * This file defines an interface for VOD server modules in vlc - */ - -/** - * \defgroup vod Video On Demand (VOD) + * \defgroup vod Video on Demand (VoD) * \ingroup server - * Video On Demand (VOD) functionality is provided from VLM. + * Video on Demand (VOD) functionality provided by VLM * @{ + * \file + * VLC VoD module interface */ struct vod_t diff --git a/include/vlc_vout.h b/include/vlc_vout.h index 15f321d1e7..189fa099f4 100644 --- a/include/vlc_vout.h +++ b/include/vlc_vout.h @@ -26,25 +26,20 @@ #ifndef VLC_VOUT_H_ #define VLC_VOUT_H_ 1 -/** - * \file - * This file defines common video output structures and functions in vlc - */ - #include #include #include -/***************************************************************************** - * Prototypes - *****************************************************************************/ - /** - * \defgroup video_output Video Output + * \defgroup video_output Video output + * Video rendering, output and window management + * * This module describes the programming interface for video output threads. * It includes functions allowing to open a new thread, send pictures to a * thread, and destroy a previously opened video output thread. * @{ + * \file + * Video output thread interface */ /** diff --git a/src/playlist/playlist_internal.h b/src/playlist/playlist_internal.h index 20f0343fdf..b2b15d4788 100644 --- a/src/playlist/playlist_internal.h +++ b/src/playlist/playlist_internal.h @@ -26,12 +26,10 @@ # define __LIBVLC_PLAYLIST_INTERNAL_H 1 /** - * \file - * This file contain internal structures and function prototypes related - * to the playlist in vlc - * - * \defgroup vlc_playlist Playlist - * @{ + * \defgroup playlist_internals VLC playlist internals + * \ingroup playlist + * \file + * VLC playlist internal interface */ #include "input/input_interface.h" @@ -143,10 +141,6 @@ int playlist_DeleteItem( playlist_t * p_playlist, playlist_item_t *, bool); void ResetCurrentlyPlaying( playlist_t *p_playlist, playlist_item_t *p_cur ); void ResyncCurrentIndex( playlist_t *p_playlist, playlist_item_t *p_cur ); -/** - * @} - */ - #define PLAYLIST_DEBUG 1 //#undef PLAYLIST_DEBUG2 @@ -176,4 +170,5 @@ static inline void pl_unlock_if( playlist_t * p_playlist, bool cond ) if( cond ) PL_UNLOCK; } +/** @} */ #endif /* !__LIBVLC_PLAYLIST_INTERNAL_H */