Added some Doxygen doc

include/vlc_common.h

@@ -3,7 +3,7 @@
  * Collection of useful common types and macros definitions
  *****************************************************************************
  * Copyright (C) 1998, 1999, 2000 VideoLAN
- * $Id: vlc_common.h,v 1.78 2003/09/13 17:42:15 fenrir Exp $
+ * $Id: vlc_common.h,v 1.79 2003/09/18 17:54:02 zorglub Exp $
  *
  * Authors: Samuel Hocevar <sam@via.ecp.fr>
  *          Vincent Seguin <seguin@via.ecp.fr>
@@ -24,6 +24,11 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/**
+ * \file 
+ * This file is a collection of common definitions and types
+ */
+
 /*****************************************************************************
  * Required vlc headers
  *****************************************************************************/

include/vlc_interface.h

@@ -4,7 +4,7 @@
  * interface, such as message output.
  *****************************************************************************
  * Copyright (C) 1999, 2000 VideoLAN
- * $Id: vlc_interface.h,v 1.5 2003/08/30 13:59:15 gbazin Exp $
+ * $Id: vlc_interface.h,v 1.6 2003/09/18 17:54:02 zorglub Exp $
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  *
@@ -25,12 +25,25 @@
 
 typedef struct intf_dialog_args_t intf_dialog_args_t;
 
+/**
+ * \file
+ * This file contains structures and function prototypes for 
+ * interface management in vlc 
+ */
+
+
 /*****************************************************************************
  * intf_thread_t: describe an interface thread
  *****************************************************************************
  * This struct describes all interface-specific data of the main (interface)
  * thread.
  *****************************************************************************/
+
+/**
+ * \defgroup vlc_interface Interface
+ * These functions and structures are for interface management
+ * @{
+ */
 struct intf_thread_t
 {
     VLC_COMMON_MEMBERS
@@ -39,14 +52,14 @@ struct intf_thread_t
     vlc_bool_t          b_block;
 
     /* Specific interfaces */
-    intf_console_t *    p_console;                                /* console */
-    intf_sys_t *        p_sys;                           /* system interface */
+    intf_console_t *    p_console;                                /** console */
+    intf_sys_t *        p_sys;                           /** system interface */
 
-    /* Interface module */
+    /** Interface module */
     module_t *   p_module;
-    void      ( *pf_run )    ( intf_thread_t * );
+    void      ( *pf_run )    ( intf_thread_t * ); /** Run function */
 
-    /* Specific for dialogs providers */
+    /** Specific for dialogs providers */
     void ( *pf_show_dialog ) ( intf_thread_t *, int, int,
                                intf_dialog_args_t * );
 
@@ -92,6 +105,8 @@ VLC_EXPORT( int,               intf_RunThread,  ( intf_thread_t * ) );
 VLC_EXPORT( void,              intf_StopThread, ( intf_thread_t * ) );
 VLC_EXPORT( void,              intf_Destroy,    ( intf_thread_t * ) );
 
+/*@}*/
+
 /*****************************************************************************
  * Macros
  *****************************************************************************/

include/vlc_objects.h

@@ -2,7 +2,7 @@
  * vlc_objects.h: vlc_object_t definition.
  *****************************************************************************
  * Copyright (C) 2002 VideoLAN
- * $Id: vlc_objects.h,v 1.17 2003/09/02 20:19:25 gbazin Exp $
+ * $Id: vlc_objects.h,v 1.18 2003/09/18 17:54:02 zorglub Exp $
  *
  * Authors: Samuel Hocevar <sam@zoy.org>
  *
@@ -21,6 +21,16 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/**
+ * \file
+ * This file defines the vlc_object_t structure and object types
+ */
+
+/** 
+ * \defgroup vlc_object Objects
+ * @{
+ */
+
 /* Object types */
 #define VLC_OBJECT_ROOT       (-1)
 #define VLC_OBJECT_VLC        (-2)
@@ -49,6 +59,7 @@
 /*****************************************************************************
  * The vlc_object_t type. Yes, it's that simple :-)
  *****************************************************************************/
+/** The main vlc_object_t structure */
 struct vlc_object_t
 {
     VLC_COMMON_MEMBERS
@@ -68,6 +79,8 @@ VLC_EXPORT( void, __vlc_object_release, ( vlc_object_t * ) );
 VLC_EXPORT( vlc_list_t *, __vlc_list_find, ( vlc_object_t *, int, int ) );
 VLC_EXPORT( void, vlc_list_release, ( vlc_list_t * ) );
 
+/*}@*/
+
 #define vlc_object_create(a,b) \
     __vlc_object_create( VLC_OBJECT(a), b )
 

src/interface/interface.c

@@ -4,7 +4,7 @@
  * interface, such as command line.
  *****************************************************************************
  * Copyright (C) 1998-2001 VideoLAN
- * $Id: interface.c,v 1.105 2003/06/26 12:19:59 sam Exp $
+ * $Id: interface.c,v 1.106 2003/09/18 17:54:02 zorglub Exp $
  *
  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  *
@@ -23,6 +23,12 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/**
+ *   \file
+ *   This file contains functions related to interface management
+ */
+
+
 /*****************************************************************************
  * Preamble
  *****************************************************************************/
@@ -53,6 +59,13 @@ static void Manager( intf_thread_t *p_intf );
  * This function opens output devices and creates specific interfaces. It sends
  * its own error messages.
  *****************************************************************************/
+/**
+ * Create the interface, and prepare it for main loop.
+ * 
+ * \param p_this the calling vlc_object_t
+ * \param psz_module a prefered interface module
+ * \return a pointer to the created interface thread, NULL on error
+ */
 intf_thread_t* __intf_Create( vlc_object_t *p_this, const char *psz_module )
 {
     intf_thread_t * p_intf;
@@ -109,6 +122,14 @@ intf_thread_t* __intf_Create( vlc_object_t *p_this, const char *psz_module )
  * This function either creates a new thread and runs the interface in it,
  * or runs the interface in the current thread, depending on b_block.
  *****************************************************************************/
+/**
+ * Run the interface thread.
+ *
+ * If b_block is not set, runs the interface in the thread, else, 
+ * creates a new thread and runs the interface.
+ * \param p_intf the interface thread
+ * \return VLC_SUCCESS on success, an error number else
+ */
 int intf_RunThread( intf_thread_t *p_intf )
 {
     if( p_intf->b_block )
@@ -146,6 +167,13 @@ int intf_RunThread( intf_thread_t *p_intf )
  *****************************************************************************
  * This function asks the interface thread to stop.
  *****************************************************************************/
+/**
+ * Stops the interface thread
+ *
+ * This function asks the interface thread to stop
+ * \param p_intf the interface thread
+ * \return nothing
+ */
 void intf_StopThread( intf_thread_t *p_intf )
 {
     /* Tell the interface to die */
@@ -163,6 +191,13 @@ void intf_StopThread( intf_thread_t *p_intf )
  *****************************************************************************
  * This function destroys specific interfaces and close output devices.
  *****************************************************************************/
+/**
+ * \brief Destroy the interface after the main loop endeed.
+ * 
+ * Destroys interfaces and output devices
+ * \param p_intf the interface thread
+ * \return nothing
+ */
 void intf_Destroy( intf_thread_t *p_intf )
 {
     /* Unlock module */
@@ -176,6 +211,8 @@ void intf_Destroy( intf_thread_t *p_intf )
 
 /* Following functions are local */
 
+
+
 /*****************************************************************************
  * Manager: helper thread for blocking interfaces
  *****************************************************************************
@@ -183,6 +220,18 @@ void intf_Destroy( intf_thread_t *p_intf )
  * p_vlc->b_die events because it is only supposed to listen to p_intf->b_die.
  * This thread takes care of the matter.
  *****************************************************************************/
+/**
+ * \brief Helper thread for blocking interfaces.
+ * \ingroup vlc_interface
+ *
+ * This is a local function
+ * If the interface is launched in the main thread, it will not listen to
+ * p_vlc->b_die events because it is only supposed to listen to p_intf->b_die.
+ * This thread takes care of the matter.
+ * \see intf_RunThread
+ * \param p_intf an interface thread
+ * \return nothing
+ */
 static void Manager( intf_thread_t *p_intf )
 {
     while( !p_intf->b_die )

src/interface/intf_eject.c

@@ -2,7 +2,7 @@
  * intf_eject.c: CD/DVD-ROM ejection handling functions
  *****************************************************************************
  * Copyright (C) 2001, 2002 VideoLAN
- * $Id: intf_eject.c,v 1.20 2003/03/24 17:15:30 gbazin Exp $
+ * $Id: intf_eject.c,v 1.21 2003/09/18 17:54:02 zorglub Exp $
  *
  * Author: Julien Blache <jb@technologeek.org> for the Linux part
  *               with code taken from the Linux "eject" command
@@ -24,6 +24,11 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/**
+ *  \file
+ *  This file contain functions to eject CD and DVD drives
+ */
+
 #include <vlc/vlc.h>
 
 #include <stdio.h>
@@ -85,6 +90,13 @@ static int EjectSCSI ( int i_fd );
  * returns 1 on failure
  * returns -1 if not implemented
  *****************************************************************************/
+/**
+ * \brief Ejects the CD /DVD
+ * \ingroup vlc_interface
+ * \param p_this the calling vlc_object_t
+ * \param psz_device the CD/DVD to eject
+ * \return 0 on success, 1 on failure, -1 if not implemented
+ */
 int __intf_Eject( vlc_object_t *p_this, const char *psz_device )
 {
     int i_ret = VLC_SUCCESS;
@@ -212,6 +224,13 @@ int __intf_Eject( vlc_object_t *p_this, const char *psz_device )
 /*****************************************************************************
  * Eject using SCSI commands. Return 0 if successful
  *****************************************************************************/
+/**
+ * \brief Ejects the CD /DVD using SCSI commands
+ * \ingroup vlc_interface
+ * This function is local
+ * \param i_fd a device nummber
+ * \return 0 on success, VLC_EGENERIC on failure
+ */
 static int EjectSCSI( int i_fd )
 {
     int i_status;

src/misc/objects.c

@@ -2,7 +2,7 @@
  * objects.c: vlc_object_t handling
  *****************************************************************************
  * Copyright (C) 2002 VideoLAN
- * $Id: objects.c,v 1.38 2003/09/02 20:19:26 gbazin Exp $
+ * $Id: objects.c,v 1.39 2003/09/18 17:54:02 zorglub Exp $
  *
  * Authors: Samuel Hocevar <sam@zoy.org>
  *
@@ -21,6 +21,12 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  *****************************************************************************/
 
+/**
+ * \file
+ * This file contains the functions to handle the vlc_object_t type
+ */
+
+
 /*****************************************************************************
  * Preamble
  *****************************************************************************/
@@ -76,6 +82,14 @@ static vlc_mutex_t    structure_lock;
  * i_type is not a known value such as VLC_OBJECT_ROOT, VLC_OBJECT_VOUT and
  * so on, vlc_object_create will use its value for the object size.
  *****************************************************************************/
+
+/** 
+ * Initialize a vlc object
+ *
+ * This function allocates memory for a vlc object and initializes it. If
+ * i_type is not a known value such as VLC_OBJECT_ROOT, VLC_OBJECT_VOUT and
+ * so on, vlc_object_create will use its value for the object size.
+ */
 void * __vlc_object_create( vlc_object_t *p_this, int i_type )
 {
     vlc_object_t * p_new;
@@ -237,9 +251,10 @@ void * __vlc_object_create( vlc_object_t *p_this, int i_type )
     return p_new;
 }
 
-/*****************************************************************************
- * vlc_object_destroy: destroy a vlc object
- *****************************************************************************
+/**
+ ****************************************************************************
+ * Destroy a vlc object
+ * 
  * This function destroys an object that has been previously allocated with
  * vlc_object_create. The object's refcount must be zero and it must not be
  * attached to other objects in any way.
@@ -325,9 +340,9 @@ void __vlc_object_destroy( vlc_object_t *p_this )
     free( p_this );
 }
 
-/*****************************************************************************
- * vlc_object_get: find an object given its ID
- *****************************************************************************
+/**
+ * find an object given its ID
+ *
  * This function looks for the object whose i_object_id field is i_id. We
  * use a dichotomy so that lookups are in log2(n).
  *****************************************************************************/
@@ -387,8 +402,9 @@ void * __vlc_object_get( vlc_object_t *p_this, int i_id )
     return NULL;
 }
 
-/*****************************************************************************
- * vlc_object_find: find a typed object and increment its refcount
+/**
+ ****************************************************************************
+ * find a typed object and increment its refcount
  *****************************************************************************
  * This function recursively looks for a given object type. i_mode can be one
  * of FIND_PARENT, FIND_CHILD or FIND_ANYWHERE.
@@ -423,8 +439,9 @@ void * __vlc_object_find( vlc_object_t *p_this, int i_type, int i_mode )
     return p_found;
 }
 
-/*****************************************************************************
- * vlc_object_yield: increment an object refcount
+/**
+ ****************************************************************************
+ * increment an object refcount
  *****************************************************************************/
 void __vlc_object_yield( vlc_object_t *p_this )
 {
@@ -433,8 +450,9 @@ void __vlc_object_yield( vlc_object_t *p_this )
     vlc_mutex_unlock( &structure_lock );
 }
 
-/*****************************************************************************
- * vlc_object_release: decrement an object refcount
+/**
+ ****************************************************************************
+ * decrement an object refcount
  *****************************************************************************/
 void __vlc_object_release( vlc_object_t *p_this )
 {
@@ -443,8 +461,9 @@ void __vlc_object_release( vlc_object_t *p_this )
     vlc_mutex_unlock( &structure_lock );
 }
 
-/*****************************************************************************
- * vlc_object_attach: attach object to a parent object
+/**
+ ****************************************************************************
+ * attach object to a parent object
  *****************************************************************************
  * This function sets p_this as a child of p_parent, and p_parent as a parent
  * of p_this. This link can be undone using vlc_object_detach.
@@ -469,8 +488,9 @@ void __vlc_object_attach( vlc_object_t *p_this, vlc_object_t *p_parent )
     vlc_mutex_unlock( &structure_lock );
 }
 
-/*****************************************************************************
- * vlc_object_detach: detach object from its parent
+/**
+ ****************************************************************************
+ * detach object from its parent
  *****************************************************************************
  * This function removes all links between an object and its parent.
  *****************************************************************************/
@@ -494,8 +514,9 @@ void __vlc_object_detach( vlc_object_t *p_this )
     vlc_mutex_unlock( &structure_lock );
 }
 
-/*****************************************************************************
- * vlc_list_find: find a list typed objects and increment their refcount
+/**
+ ****************************************************************************
+ * find a list typed objects and increment their refcount
  *****************************************************************************
  * This function recursively looks for a given object type. i_mode can be one
  * of FIND_PARENT, FIND_CHILD or FIND_ANYWHERE.