Commit 402252af authored by zorglub's avatar zorglub

Added some Doxygen doc

parent a5a7097d
......@@ -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
*****************************************************************************/
......
......@@ -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
*****************************************************************************/
......
......@@ -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 )
......
......@@ -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 )
......
......@@ -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;
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment