mediacontrol: doxygen updates

include/vlc/mediacontrol.h

@@ -21,6 +21,14 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  *****************************************************************************/
 
+/**
+ * \defgroup mediacontrol MediaControl 
+ * This is the MediaControl API, * intended to provide a generic API to movie players.
+ *
+ * @{
+ */
+
+
 #ifndef _VLC_CONTROL_H
 #define _VLC_CONTROL_H 1
 
@@ -36,10 +44,10 @@ extern "C" {
 
 #include <vlc/mediacontrol_structures.h>
 
-/************************************************************************
- * Position Object Manipulation
- *************************************************************************/
-
+/**
+ * RGBPicture structure
+ * This generic structure holds a picture in an encoding specified by type.
+ */
 typedef struct {
     int  width;
     int  height;
@@ -49,6 +57,10 @@ typedef struct {
     char *data;
 } mediacontrol_RGBPicture;
 
+/**
+ * Playlist sequence
+ * A simple list of strings.
+ */
 typedef struct {
     int size;
     char **data;
@@ -59,18 +71,24 @@ typedef struct {
     char *message;
 } mediacontrol_Exception;
 
-/* Exception codes */
+/**
+ * Exception codes
+ */
 #define mediacontrol_PositionKeyNotSupported    1
 #define mediacontrol_PositionOriginNotSupported 2
 #define mediacontrol_InvalidPosition            3
 #define mediacontrol_PlaylistException          4
 #define mediacontrol_InternalException          5
 
-/* mediacontrol_Instance is an opaque structure, defined in
-   mediacontrol_internal.h. API users do not have to mess with it. */
+/**
+ * mediacontrol_Instance is an opaque structure, defined in
+ * mediacontrol_internal.h. API users do not have to mess with it. 
+ */
 typedef struct mediacontrol_Instance mediacontrol_Instance;
 
-/* Cf stream_control.h */
+/**
+ * Possible player status
+ */
 enum mediacontrol_PlayerStatusList
 {
     mediacontrol_PlayingStatus, mediacontrol_PauseStatus,
@@ -80,6 +98,10 @@ enum mediacontrol_PlayerStatusList
 };
 typedef enum mediacontrol_PlayerStatusList mediacontrol_PlayerStatus;
 
+/**
+ * Stream information
+ * This structure allows to quickly get various informations about the stream.
+ */
 typedef struct {
     mediacontrol_PlayerStatus streamstatus;
     char *url;         /* The URL of the current media stream */
@@ -91,8 +113,16 @@ typedef struct {
  *  Helper functions
  ***************************************************************************/
 
+/**
+ * Allocate a RGBPicture structure.
+ * \param datasize: the size of the data
+ */
 mediacontrol_RGBPicture *mediacontrol_RGBPicture__alloc( int datasize );
 
+/**
+ * Free a RGBPicture structure.
+ * \param pic: the RGBPicture structure
+ */
 void mediacontrol_RGBPicture__free( mediacontrol_RGBPicture *pic );
 
 mediacontrol_RGBPicture *
@@ -103,58 +133,144 @@ mediacontrol_PlaylistSeq *mediacontrol_PlaylistSeq__alloc( int size );
 
 void mediacontrol_PlaylistSeq__free( mediacontrol_PlaylistSeq *ps );
 
+/**
+ * Initialize an exception structure.
+ * \param p_exception the exception to initialize. If NULL, a new exception will be created.
+ * \return the exception
+ */
 mediacontrol_Exception *
   mediacontrol_exception_init( mediacontrol_Exception *exception );
 
+/**
+ * Free an exception structure.
+ * \return the exception
+ */
 void mediacontrol_exception_free(mediacontrol_Exception *exception);
 
 /*****************************************************************************
  * Core functions
  *****************************************************************************/
+
+/**
+ * Create a MediaControl instance with parameters
+ * \param argc the number of arguments
+ * \param argv parameters
+ * \param exception an initialized exception pointer
+ * \return a mediacontrol_Instance
+ */
 mediacontrol_Instance *
 mediacontrol_new( int argc, char **argv, mediacontrol_Exception *exception );
 
-/* Bridge with the libvlc API */
+/**
+ * Create a MediaControl instance from an existing libvlc instance
+ * \param p_instance the libvlc instance
+ * \param exception an initialized exception pointer
+ * \return a mediacontrol_Instance
+ */
 mediacontrol_Instance *
 mediacontrol_new_from_instance( libvlc_instance_t* p_instance,
 				mediacontrol_Exception *exception );
 
+/**
+ * Get the associated libvlc instance
+ * \param self: the mediacontrol instance
+ * \return a libvlc instance
+ */
 libvlc_instance_t*
 mediacontrol_get_libvlc_instance( mediacontrol_Instance* self );
 
+/**
+ * Get the current position
+ * \param self the mediacontrol instance
+ * \param an_origin the position origin
+ * \param a_key the position unit
+ * \param exception an initialized exception pointer
+ * \return a mediacontrol_Position
+ */
 mediacontrol_Position * mediacontrol_get_media_position(
                          mediacontrol_Instance *self,
                          const mediacontrol_PositionOrigin an_origin,
                          const mediacontrol_PositionKey a_key,
                          mediacontrol_Exception *exception );
 
+/**
+ * Set the position
+ * \param self the mediacontrol instance
+ * \param a_position a mediacontrol_Position
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_set_media_position( mediacontrol_Instance *self,
                                       const mediacontrol_Position *a_position,
                                       mediacontrol_Exception *exception );
 
+/**
+ * Play the movie at a given position
+ * \param self the mediacontrol instance
+ * \param a_position a mediacontrol_Position
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_start( mediacontrol_Instance *self,
                          const mediacontrol_Position *a_position,
                          mediacontrol_Exception *exception );
 
+/**
+ * Pause the movie at a given position
+ * \param self the mediacontrol instance
+ * \param a_position a mediacontrol_Position (ignored for now)
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_pause( mediacontrol_Instance *self,
                          const mediacontrol_Position *a_position,
                          mediacontrol_Exception *exception );
 
+/**
+ * Resume the movie at a given position
+ * \param self the mediacontrol instance
+ * \param a_position a mediacontrol_Position (ignored for now)
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_resume( mediacontrol_Instance *self,
                           const mediacontrol_Position *a_position,
                           mediacontrol_Exception *exception );
 
+/**
+ * Stop the movie at a given position
+ * \param self the mediacontrol instance
+ * \param a_position a mediacontrol_Position (ignored for now)
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_stop( mediacontrol_Instance *self,
                         const mediacontrol_Position *a_position,
                         mediacontrol_Exception *exception );
 
+/**
+ * Exit the player
+ * \param self the mediacontrol instance
+ */
 void mediacontrol_exit( mediacontrol_Instance *self );
 
+/**
+ * Add a new MRL to the playlist
+ * \param self the mediacontrol instance
+ * \param psz_file the MRL
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_playlist_add_item( mediacontrol_Instance *self,
                                      const char* psz_file,
                                      mediacontrol_Exception *exception );
+/**
+ * Clear the playlist
+ * \param self the mediacontrol instance
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_playlist_clear( mediacontrol_Instance *self,
                                   mediacontrol_Exception *exception );
+/**
+ * Get a flattened view of the playlist
+ * \param self the mediacontrol instance
+ * \param exception an initialized exception pointer
+ * \return a list of strings
+ */
 mediacontrol_PlaylistSeq *
   mediacontrol_playlist_get_list( mediacontrol_Instance *self,
                                   mediacontrol_Exception *exception );
@@ -163,50 +279,118 @@ mediacontrol_PlaylistSeq *
 /*****************************************************************************
  * A/V functions
  *****************************************************************************/
+/**
+ * Get a snapshot
+ * \param self the mediacontrol instance
+ * \param a_position the desired position (ignored for now)
+ * \param exception an initialized exception pointer
+ * \return a RGBpicture
+ */
 mediacontrol_RGBPicture *
   mediacontrol_snapshot( mediacontrol_Instance *self,
                          const mediacontrol_Position *a_position,
                          mediacontrol_Exception *exception );
 
 /* Return a NULL terminated list */
+/**
+ * Get a list of all cached snapshots (unimplemented)
+ * \param self the mediacontrol instance
+ * \param exception an initialized exception pointer
+ * \return a NULL-terminated list of RGBpicture
+ */
 mediacontrol_RGBPicture **
   mediacontrol_all_snapshots( mediacontrol_Instance *self,
                               mediacontrol_Exception *exception );
 
-/* Displays the message string, between "begin" and "end" positions */
+/**
+ *  Displays the message string, between "begin" and "end" positions.
+ * \param self the mediacontrol instance
+ * \param message the message to display
+ * \param begin the begin position
+ * \param end the end position
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_display_text( mediacontrol_Instance *self,
                                 const char *message,
                                 const mediacontrol_Position *begin,
                                 const mediacontrol_Position *end,
                                 mediacontrol_Exception *exception );
 
+/**
+ *  Get information about a stream
+ * \param self the mediacontrol instance
+ * \param a_key the time unit
+ * \param exception an initialized exception pointer
+ * \return a mediacontrol_StreamInformation
+ */
 mediacontrol_StreamInformation *
   mediacontrol_get_stream_information( mediacontrol_Instance *self,
                                        mediacontrol_PositionKey a_key,
                                        mediacontrol_Exception *exception );
 
+/**
+ * Get the current audio level, normalized in [0..100]
+ * \param self the mediacontrol instance
+ * \param exception an initialized exception pointer
+ * \return the volume
+ */
 unsigned short
   mediacontrol_sound_get_volume( mediacontrol_Instance *self,
                                  mediacontrol_Exception *exception );
+/**
+ * Set the audio level
+ * \param self the mediacontrol instance
+ * \param volume the volume (normalized in [0..100])
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_sound_set_volume( mediacontrol_Instance *self,
                                     const unsigned short volume,
                                     mediacontrol_Exception *exception );
 
+/**
+ * Set the video output window
+ * \param self the mediacontrol instance
+ * \param visual_id the Xid or HWND, depending on the platform
+ * \param exception an initialized exception pointer
+ */
 vlc_bool_t mediacontrol_set_visual( mediacontrol_Instance *self,
                                     WINDOWHANDLE visual_id,
                                     mediacontrol_Exception *exception );
 
-/* Rate in percent. 100 is normal rate. */
+/**
+ * Get the current playing rate, in percent
+ * \param self the mediacontrol instance
+ * \param exception an initialized exception pointer
+ * \return the rate
+ */
 int mediacontrol_get_rate( mediacontrol_Instance *self,
 			   mediacontrol_Exception *exception );
 
+/**
+ * Set the playing rate, in percent
+ * \param self the mediacontrol instance
+ * \param rate the desired rate
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_set_rate( mediacontrol_Instance *self,
 			    const int rate,
 			    mediacontrol_Exception *exception );
 
+/**
+ * Get current fullscreen status
+ * \param self the mediacontrol instance
+ * \param exception an initialized exception pointer
+ * \return the fullscreen status
+ */
 int mediacontrol_get_fullscreen( mediacontrol_Instance *self,
 				 mediacontrol_Exception *exception );
 
+/**
+ * Set fullscreen status
+ * \param self the mediacontrol instance
+ * \param b_fullscreen the desired status
+ * \param exception an initialized exception pointer
+ */
 void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
 				  const int b_fullscreen,
 				  mediacontrol_Exception *exception );
@@ -216,3 +400,5 @@ void mediacontrol_set_fullscreen( mediacontrol_Instance *self,
 # endif
 
 #endif
+
+/** @} */

include/vlc/mediacontrol_structures.h

@@ -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.
  *****************************************************************************/
+/**
+ * \defgroup mediacontrol_structures MediaControl Structures
+ * Data structures used in the MediaControl API.
+ *
+ * @{
+ */
 
 #ifndef _VLC_CONTROL_STRUCTURES_H
 #define _VLC_CONTROL_STRUCTURES_H 1
@@ -28,18 +34,33 @@
 extern "C" {
 # endif
 
+/**
+ * A position may have different origins: 
+ *  - absolute counts from the movie start
+ *  - relative counts from the current position
+ *  - modulo counts from the current position and wraps at the end of the movie
+ */
 typedef enum  {
     mediacontrol_AbsolutePosition,
     mediacontrol_RelativePosition,
     mediacontrol_ModuloPosition
 } mediacontrol_PositionOrigin;
 
+/**
+ * Units available in mediacontrol Positions
+ *  - ByteCount number of bytes
+ *  - SampleCount number of frames
+ *  - MediaTime time in milliseconds
+ */
 typedef enum {
     mediacontrol_ByteCount,
     mediacontrol_SampleCount,
     mediacontrol_MediaTime
 } mediacontrol_PositionKey;
 
+/**
+ * MediaControl Position
+ */
 typedef struct {
     mediacontrol_PositionOrigin origin;
     mediacontrol_PositionKey key;
@@ -51,3 +72,5 @@ typedef struct {
 # endif
 
 #endif
+
+/** @} */