From: Clément Stenac Date: Thu, 18 Sep 2003 17:54:02 +0000 (+0000) Subject: Added some Doxygen doc X-Git-Tag: 0.7.0~931 X-Git-Url: https://git.sesse.net/?a=commitdiff_plain;h=402252afb6ed22e64ca80ba6625a3635ad6fddb2;p=vlc Added some Doxygen doc --- diff --git a/include/vlc_common.h b/include/vlc_common.h index b667e0ec7b..ff3edfbbea 100644 --- a/include/vlc_common.h +++ b/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 * Vincent Seguin @@ -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 *****************************************************************************/ diff --git a/include/vlc_interface.h b/include/vlc_interface.h index 90b69fbf19..cbf10ea380 100644 --- a/include/vlc_interface.h +++ b/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 * @@ -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 *****************************************************************************/ diff --git a/include/vlc_objects.h b/include/vlc_objects.h index d2954db549..7ebbb0ff28 100644 --- a/include/vlc_objects.h +++ b/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 * @@ -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 ) diff --git a/src/interface/interface.c b/src/interface/interface.c index 8fa992d36b..4807777807 100644 --- a/src/interface/interface.c +++ 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 * @@ -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 ) diff --git a/src/interface/intf_eject.c b/src/interface/intf_eject.c index 36e0f5e131..6f3bd04f5f 100644 --- a/src/interface/intf_eject.c +++ b/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 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 #include @@ -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; diff --git a/src/misc/objects.c b/src/misc/objects.c index 6ff8076759..239fcc0787 100644 --- a/src/misc/objects.c +++ b/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 * @@ -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.