Add another bunch of doxygen file comments.

include/vlc/deprecated.h

 /*****************************************************************************
  * deprecated.h:  libvlc deprecated API
  *****************************************************************************
- * Copyright (C) 1998-2005 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Clément Stenac <zorglub@videolan.org>
- *          Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
+ *          Jean-Paul Saman <jpsaman@videolan.org>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -25,6 +25,11 @@
 #ifndef LIBVLC_DEPRECATED_H
 #define LIBVLC_DEPRECATED_H 1
 
+/**
+ * \file
+ * This file defines libvlc depreceated API
+ */
+
 # ifdef __cplusplus
 extern "C" {
 # endif

include/vlc/libvlc.h

@@ -5,7 +5,7 @@
  * $Id$
  *
  * Authors: Clément Stenac <zorglub@videolan.org>
- *          Jean-Paul Saman <jpsaman _at_ m2x _dot_ nl>
+ *          Jean-Paul Saman <jpsaman@videolan.org>
  *          Pierre d'Herbemont <pdherbemont@videolan.org>
  *
  * This program is free software; you can redistribute it and/or modify
@@ -23,6 +23,11 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \file
+ * This file defines libvlc external API
+ */
+
 /**
  * \defgroup libvlc libvlc
  * This is libvlc, the base library of the VLC program.
@@ -30,7 +35,6 @@
  * @{
  */
 
-
 #ifndef VLC_LIBVLC_H
 #define VLC_LIBVLC_H 1
 
@@ -527,6 +531,7 @@ VLC_PUBLIC_API libvlc_drawable_t
                     libvlc_media_player_get_drawable ( libvlc_media_player_t *, libvlc_exception_t * );
 
 /** \bug This might go away ... to be replaced by a broader system */
+
 /**
  * Get the current movie length (in ms).
  *
@@ -534,7 +539,8 @@ VLC_PUBLIC_API libvlc_drawable_t
  * \param p_e an initialized exception pointer
  * \return the movie length (in ms).
  */
-VLC_PUBLIC_API libvlc_time_t  libvlc_media_player_get_length     ( libvlc_media_player_t *, libvlc_exception_t *);
+VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *, libvlc_exception_t *);
+
 /**
  * Get the current movie time (in ms).
  *
@@ -542,7 +548,8 @@ VLC_PUBLIC_API libvlc_time_t  libvlc_media_player_get_length     ( libvlc_media_
  * \param p_e an initialized exception pointer
  * \return the movie time (in ms).
  */
-VLC_PUBLIC_API libvlc_time_t  libvlc_media_player_get_time       ( libvlc_media_player_t *, libvlc_exception_t *);
+VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *, libvlc_exception_t *);
+
 /**
  * Set the movie time (in ms).
  *
@@ -550,17 +557,90 @@ VLC_PUBLIC_API libvlc_time_t  libvlc_media_player_get_time       ( libvlc_media_
  * \param the movie time (in ms).
  * \param p_e an initialized exception pointer
  */
-VLC_PUBLIC_API void           libvlc_media_player_set_time       ( libvlc_media_player_t *, libvlc_time_t, libvlc_exception_t *);
-VLC_PUBLIC_API float          libvlc_media_player_get_position   ( libvlc_media_player_t *, libvlc_exception_t *);
-VLC_PUBLIC_API void           libvlc_media_player_set_position   ( libvlc_media_player_t *, float, libvlc_exception_t *);
-VLC_PUBLIC_API void           libvlc_media_player_set_chapter    ( libvlc_media_player_t *, int, libvlc_exception_t *);
-VLC_PUBLIC_API int            libvlc_media_player_get_chapter    (libvlc_media_player_t *, libvlc_exception_t *);
+VLC_PUBLIC_API void libvlc_media_player_set_time( libvlc_media_player_t *, libvlc_time_t, libvlc_exception_t *);
+
+/**
+ * Get movie position.
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return movie position
+ */
+VLC_PUBLIC_API float libvlc_media_player_get_position( libvlc_media_player_t *, libvlc_exception_t *);
+
+/**
+ * Set movie position.
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return movie position
+ */
+VLC_PUBLIC_API void libvlc_media_player_set_position( libvlc_media_player_t *, float, libvlc_exception_t *);
+
+/**
+ * Set movie chapter
+ *
+ * \param p_mi the Media Player
+ * \param i_chapter chapter number to play
+ * \param p_e an initialized exception pointer
+ */
+VLC_PUBLIC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *, int, libvlc_exception_t *);
+
+/**
+ * Get movie chapter
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return chapter number currently playing
+ */
+VLC_PUBLIC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *, libvlc_exception_t * );
+
+/**
+ * Get movie chapter count
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return number of chapters in movie
+ */
 VLC_PUBLIC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *, libvlc_exception_t *);
 VLC_PUBLIC_API int libvlc_media_player_will_play        ( libvlc_media_player_t *, libvlc_exception_t *);
-VLC_PUBLIC_API float          libvlc_media_player_get_rate       ( libvlc_media_player_t *, libvlc_exception_t *);
-VLC_PUBLIC_API void           libvlc_media_player_set_rate       ( libvlc_media_player_t *, float, libvlc_exception_t *);
-VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state   ( libvlc_media_player_t *, libvlc_exception_t *);
+
+/**
+ * Get movie play rate
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return movie play rate
+ */
+VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t *, libvlc_exception_t *);
+
+/**
+ * Set movie play rate
+ *
+ * \param p_mi the Media Player
+ * \param movie play rate to set
+ * \param p_e an initialized exception pointer
+ */
+VLC_PUBLIC_API void libvlc_media_player_set_rate( libvlc_media_player_t *, float, libvlc_exception_t *);
+
+/**
+ * Get current movie state
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return current movie state as libvlc_state_t
+ */
+VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *, libvlc_exception_t *);
+
+/**
+ * Get movie fps rate
+ *
+ * \param p_mi the Media Player
+ * \param p_e an initialized exception pointer
+ * \return frames per second (fps) for this playing movie
+ */
 VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t *, libvlc_exception_t *);
+
 /** end bug */
 
 /**

include/vlc/libvlc_events.h

 /*****************************************************************************
  * libvlc_events.h:  libvlc_events external API structure
  *****************************************************************************
- * Copyright (C) 1998-2007 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id $
  *
  * Authors: Filippo Carone <littlejohn@videolan.org>
@@ -25,6 +25,11 @@
 #ifndef LIBVLC_EVENTS_H
 #define LIBVLC_EVENTS_H 1
 
+/**
+ * \file
+ * This file defines libvlc_event external API
+ */
+
 # ifdef __cplusplus
 extern "C" {
 # endif

include/vlc/libvlc_media_list.h

 /*****************************************************************************
  * libvlc_media_list.h:  libvlc_media_list API
  *****************************************************************************
- * Copyright (C) 1998-2005 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Pierre d'Herbemont
@@ -24,6 +24,11 @@
 #ifndef LIBVLC_MEDIA_LIST_H
 #define LIBVLC_MEDIA_LIST_H 1
 
+/**
+ * \file
+ * This file defines libvlc_media_list API
+ */
+
 # ifdef __cplusplus
 extern "C" {
 # endif

include/vlc/libvlc_structures.h

 /*****************************************************************************
  * libvlc.h:  libvlc_* new external API structures
  *****************************************************************************
- * Copyright (C) 1998-2007 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id $
  *
  * Authors: Filippo Carone <littlejohn@videolan.org>
@@ -24,6 +24,11 @@
 #ifndef LIBVLC_STRUCTURES_H
 #define LIBVLC_STRUCTURES_H 1
 
+/**
+ * \file
+ * This file defines libvlc_* new external API structures
+ */
+
 #include <stdint.h>
 
 # ifdef __cplusplus

include/vlc/libvlc_vlm.h

 /*****************************************************************************
  * libvlc_vlm.h:  libvlc_* new external API
  *****************************************************************************
- * Copyright (C) 1998-2005 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Clément Stenac <zorglub@videolan.org>
@@ -25,6 +25,11 @@
 #ifndef LIBVLC_VLM_H
 #define LIBVLC_VLM_H 1
 
+/**
+ * \file
+ * This file defines libvlc_vlm_* external API
+ */
+
 # ifdef __cplusplus
 extern "C" {
 # endif

include/vlc/mediacontrol.h

 /*****************************************************************************
- * control.h: global header for mediacontrol
+ * mediacontrol.h: global header for mediacontrol
  *****************************************************************************
- * Copyright (C) 2005 the VideoLAN team
+ * Copyright (C) 2005-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
@@ -21,6 +21,11 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \file
+ * This file defines libvlc mediacontrol_* external API
+ */
+
 /**
  * \defgroup mediacontrol MediaControl
  * This is the MediaControl API, * intended to provide a generic API to movie players.

include/vlc/mediacontrol_structures.h

 /*****************************************************************************
- * control_structures.h: global header for mediacontrol
+ * mediacontrol_structures.h: global header for mediacontrol
  *****************************************************************************
- * Copyright (C) 2005 the VideoLAN team
+ * Copyright (C) 2005-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Olivier Aubert <olivier.aubert@liris.univ-lyon1.fr>
@@ -20,6 +20,12 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
+
+/**
+ * \file
+ * This file defines libvlc mediacontrol_* data structures
+ */
+
 /**
  * \defgroup mediacontrol_structures MediaControl Structures
  * Data structures used in the MediaControl API.

include/vlc/vlc.h

 /*****************************************************************************
  * vlc.h: global header for libvlc
  *****************************************************************************
- * Copyright (C) 1998-2004 the VideoLAN team
+ * Copyright (C) 1998-2008 the VideoLAN team
  * $Id$
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
@@ -28,6 +28,11 @@
 #ifndef VLC_VLC_H
 #define VLC_VLC_H 1
 
+/**
+ * \file
+ * This file defines libvlc new external API
+ */
+
 # ifdef __cplusplus
 extern "C" {
 # endif