include: improve Doxygen modules

In particular, move \file stanzas inside groups.
croepha · Jun 14, 2015 · 4ee1038 · 4ee1038
1 parent e2fcd5b
commit 4ee1038
Show file tree

Hide file tree

Showing 29 changed files with 109 additions and 189 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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;

diff --git 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
@@ -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

diff --git a/include/vlc_codec.h b/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 */
diff --git 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 <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

diff --git 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
@@ -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;

diff --git 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 <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
diff --git 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;