include: improve Doxygen modules

In particular, move \file stanzas inside groups.

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
  */
 
 /**

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

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;

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;

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;

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;

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;

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 <stdbool.h>
 # 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;

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
  *

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 <vlc_block.h>
 
 /**
  * \defgroup access Access
+ * \ingroup input
+ * Raw input byte streams
  * @{
+ * \file
+ * Input byte stream modules interface
  */
 
 enum access_query_e

include/vlc_codec.h

@@ -29,18 +29,17 @@
 #include <vlc_picture.h>
 #include <vlc_subpicture.h>
 
-/**
- * \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 */

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 <vlc_es.h>
 #include <vlc_stream.h>
 #include <vlc_es_out.h>
 
 /**
- * \defgroup demux Demux
+ * \defgroup demux Demultiplexer
+ * \ingroup input
+ * Demultiplexers (file format parsers)
  * @{
+ * \file
+ * Demultiplexer modules interface
  */
 
 struct demux_t

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

include/vlc_filter.h

@@ -31,8 +31,11 @@
 #include <vlc_mouse.h>
 
 /**
+ * \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;

include/vlc_input.h

@@ -22,13 +22,15 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
-/* __ is need because conflict with <vlc/input.h> */
 #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 <vlc_es.h>
@@ -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

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;

include/vlc_memory.h

@@ -25,14 +25,11 @@
 
 #include <stdlib.h>
 
-/**
- * \file
- * This file deals with memory fixups
- */
-
 /**
  * \defgroup memory Memory
  * @{
+ * \file
+ * Memory fixups
  */
 
 /**

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 <stdarg.h>
 
 /**
- * \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 */

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 */

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 */

include/vlc_stream.h

@@ -26,20 +26,16 @@
 
 #include <vlc_block.h>
 
-/**
- * \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 */

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 )

include/vlc_subpicture.h

@@ -27,19 +27,19 @@
 #define VLC_SUBPICTURE_H 1
 
 /**
- * \file
- * This file defines subpicture structures and functions in vlc
  */
 
 #include <vlc_picture.h>
 #include <vlc_text_style.h>
 
 /**
- * \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
  */
 
 /**

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
  * @{
  */
 

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

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 <vlc_input.h>
 
 /**
  * \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 */

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

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 <vlc_picture.h>
 #include <vlc_filter.h>
 #include <vlc_subpicture.h>
 
-/*****************************************************************************
- * 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
  */
 
 /**

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 */