[MPlayer-cvslog] CVS: main m_config.c, 1.15, 1.16 m_config.h, 1.7, 1.8 m_option.c, 1.49, 1.50 m_option.h, 1.14, 1.15 m_property.c, 1.3, 1.4 m_property.h, 1.3, 1.4 m_struct.c, 1.4, 1.5 m_struct.h, 1.3, 1.4

[Alban Bedel CVS]

CVS change done by Alban Bedel CVS

Update of /cvsroot/mplayer/main
In directory mail:/var2/tmp/cvs-serv25547

Modified Files:
	m_config.c m_config.h m_option.c m_option.h m_property.c 
	m_property.h m_struct.c m_struct.h 
Log Message:
Doxygen attack!


Index: m_config.c
===================================================================
RCS file: /cvsroot/mplayer/main/m_config.c,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- m_config.c	13 Mar 2006 21:18:27 -0000	1.15
+++ m_config.c	24 Apr 2006 19:20:03 -0000	1.16
@@ -1,3 +1,7 @@
+
+/// \file
+/// \ingroup Config
+
 #include "config.h"
 
 #include <stdlib.h>

Index: m_config.h
===================================================================
RCS file: /cvsroot/mplayer/main/m_config.h,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- m_config.h	24 Jan 2006 11:16:13 -0000	1.7
+++ m_config.h	24 Apr 2006 19:20:03 -0000	1.8
@@ -1,89 +1,200 @@
 #ifndef _M_CONFIG_H
 #define _M_CONFIG_H
 
+/// \defgroup Config Config manager
+///
+/// m_config provide an API to manipulate the config variables in MPlayer.
+/// It make use of the \ref Options API to provide a context stack that
+/// allow saving and later restoring the state of all variables.
+///@{
+
+/// \file
+
 typedef struct m_config_option m_config_option_t;
 typedef struct m_config_save_slot m_config_save_slot_t;
+/// \ingroup ConfigProfiles
 typedef struct m_profile m_profile_t;
 struct m_option;
 struct m_option_type;
 
+/// Config option save slot
 struct m_config_save_slot {
+  /// Previous level slot.
   m_config_save_slot_t* prev;
+  /// Level at which the save was made.
   int lvl;
   // we have to store other datatypes in this as well,
   // so make sure we get properly aligned addresses
   unsigned char data[0] __attribute__ ((aligned (8)));
 };
 
+/// Config option
 struct m_config_option {
   m_config_option_t* next;
-  char* name; // Full name (ie option:subopt)
+  /// Full name (ie option:subopt).
+  char* name;
+  /// Option description.
   struct m_option* opt;
+  /// Save slot stack.
   m_config_save_slot_t* slots;
-  unsigned int flags; // currently it only tell if the option was set
+  /// See \ref ConfigOptionFlags.
+  unsigned int flags;
 };
 
+/// \defgroup ConfigProfiles Config profiles
+/// \ingroup Config
+///
+/// Profiles allow to predefine some set of options that can then
+/// be applied later on with the internal -profile option.
+///
+///@{
+
+/// Config profile
 struct m_profile {
   m_profile_t* next;
   char* name;
   char* desc;
   int num_opts;
+  /// Option/value pair array.
   char** opts;
 };
 
+///@}
+
+/// Config object
+/** \ingroup Config */
 typedef struct m_config {
+  /// Registered options.
+  /** This contain all options and suboptions.
+   */ 
   m_config_option_t* opts;
-  int lvl; // Current stack level
+  /// Current stack level.
+  int lvl;
+  /// \ref OptionParserModes
   int mode;
+  /// List of the defined profiles.
   m_profile_t* profiles;
+  /// Depth when recursively including profiles.
   int profile_depth;
+  /// Options defined by the config itself.
   struct m_option* self_opts;
 } m_config_t;
 
+/// \defgroup ConfigOptionFlags Config option flags
+/// \ingroup Config
+///@{
+
+/// Set if an option have been set at the current level.
 #define M_CFG_OPT_SET    (1<<0)
-#define M_CFG_OPT_ALIAS  (1<<1)
 
+/// Set if another option already use the same variable.
+#define M_CFG_OPT_ALIAS  (1<<1)
 
-//////////////////////////// Functions ///////////////////////////////////
+///@}
 
+/// Create a new config object.
+/** \ingroup Config
+ */
 m_config_t*
 m_config_new(void);
 
+/// Free a config object.
 void
 m_config_free(m_config_t* config);
 
+/// Push a new context.
+/** \param config The config object.
+ */
 void
 m_config_push(m_config_t* config);
 
+/// Pop the current context restoring the previous context state.
+/** \param config The config object.
+ */
 void
 m_config_pop(m_config_t* config);
 
+/// Register some options to be used.
+/** \param config The config object.
+ *  \param args An array of \ref m_option struct.
+ *  \return 1 on success, 0 on failure.
+ */
 int
 m_config_register_options(m_config_t *config, struct m_option *args);
 
+/// Set an option.
+/** \param config The config object.
+ *  \param arg The option's name.
+ *  \param param The value of the option, can be NULL.
+ *  \return See \ref OptionParserReturn.
+ */
 int
 m_config_set_option(m_config_t *config, char* arg, char* param);
 
+/// Check if an option setting is valid.
+/** \param config The config object.
+ *  \param arg The option's name.
+ *  \param param The value of the option, can be NULL.
+ *  \return See \ref OptionParserReturn.
+ */
 int
 m_config_check_option(m_config_t *config, char* arg, char* param);
 
+/// Get the option matching the given name.
+/** \param config The config object.
+ *  \param arg The option's name.
+ */
 struct m_option*
 m_config_get_option(m_config_t *config, char* arg);
 
+/// Print a list of all registered options.
+/** \param config The config object.
+ */
 void
 m_config_print_option_list(m_config_t *config);
 
+/// \addtogroup ConfigProfiles
+///@{
+
+/// Find the profile with the given name.
+/** \param config The config object.
+ *  \param arg The profile's name.
+ *  \return The profile object or NULL.
+ */
 m_profile_t*
 m_config_get_profile(m_config_t* config, char* name);
 
+/// Get the profile with the given name, creating it if necessary.
+/** \param config The config object.
+ *  \param arg The profile's name.
+ *  \return The profile object.
+ */
 m_profile_t*
 m_config_add_profile(m_config_t* config, char* name);
 
+/// Set the description of a profile.
+/** This is used by the config file parser when defining a profile. 
+ * 
+ *  \param p The profile object.
+ *  \param arg The profile's name.
+ */
 void
 m_profile_set_desc(m_profile_t* p, char* desc);
 
+/// Add an option to a profile.
+/** This is used by the config file parser when defining a profile. 
+ * 
+ *  \param config The config object.
+ *  \param p The profile object.
+ *  \param name The option's name.
+ *  \param val The option's value.
+ */
 int
 m_config_set_profile_option(m_config_t* config, m_profile_t* p,
 			    char* name, char* val);
 
+///@}
+
+///@}
+
 #endif /* _M_CONFIG_H */

Index: m_option.c
===================================================================
RCS file: /cvsroot/mplayer/main/m_option.c,v
retrieving revision 1.49
retrieving revision 1.50
diff -u -r1.49 -r1.50
--- m_option.c	24 Apr 2006 07:20:32 -0000	1.49
+++ m_option.c	24 Apr 2006 19:20:03 -0000	1.50
@@ -1,3 +1,7 @@
+
+/// \file
+/// \ingroup Options
+
 #include "config.h"
 
 #include <stdlib.h>

Index: m_option.h
===================================================================
RCS file: /cvsroot/mplayer/main/m_option.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- m_option.h	24 Jan 2006 11:14:13 -0000	1.14
+++ m_option.h	24 Apr 2006 19:20:04 -0000	1.15
@@ -1,10 +1,23 @@
 #ifndef _M_OPTION_H
 #define _M_OPTION_H
 
+/// \defgroup Options
+/// m_option allow to parse, print and copy data of various types.
+/// It is the base of the \ref OptionsStruct, \ref Config and
+/// \ref Properties APIs.
+///@{
+
+/// \file m_option.h
+
+/// \ingroup OptionTypes
 typedef struct m_option_type m_option_type_t;
 typedef struct m_option m_option_t;
 struct m_struct_st;
 
+/// \defgroup OptionTypes Options types
+/// \ingroup Options
+///@{
+
 ///////////////////////////// Options types declarations ////////////////////////////
 
 // Simple types
@@ -28,52 +41,99 @@
 extern m_option_type_t m_option_type_func_param;
 extern m_option_type_t m_option_type_func;
 
+/// Callback used to reset func options.
 typedef void (*m_opt_default_func_t)(m_option_t *, char*);
+
+/// Callback used by m_option_type_func_full options.
 typedef int (*m_opt_func_full_t)(m_option_t *, char *, char *);
+
+/// Callback used by m_option_type_func_param options.
 typedef int (*m_opt_func_param_t)(m_option_t *, char *);
+
+/// Callback used by m_option_type_func options.
 typedef int (*m_opt_func_t)(m_option_t *);
-///////////// Backward compat
+
+// Backward compat
 typedef m_opt_default_func_t cfg_default_func_t;
 typedef m_opt_func_full_t cfg_func_arg_param_t;
 typedef m_opt_func_param_t cfg_func_param_t;
 typedef m_opt_func_t cfg_func_t;
 
+/// Extra definition needed for \ref m_option_type_obj_settings_list options.
 typedef struct {
+  /// Pointer to an array of pointer to some object type description struct.
   void** list;
+  /// Offset of the object type name (char*) in the description struct.
   void* name_off;
+  /// Offset of the object type info string (char*) in the description struct.
   void* info_off;
+  /// \brief Offset of the object type parameter description (\ref m_struct_st)
+  /// in the description struct.
   void* desc_off;
 } m_obj_list_t;
 
-typedef struct {
+/// The data type used by \ref m_option_type_obj_settings_list.
+typedef struct m_obj_settings {
+  /// Type of the object.
   char* name;
+  /// NULL terminated array of parameter/value pairs.
   char** attribs;
 } m_obj_settings_t;
-extern m_option_type_t m_option_type_obj_settings_list;
-
-// Presets are mean to be used with options struct
 
+/// A parser to setup a list of objects.
+/** It create a NULL terminated array \ref m_obj_settings. The option priv
+ *  field (\ref m_option::priv) must point to a \ref m_obj_list_t describing
+ *  the available object types.
+ */
+extern m_option_type_t m_option_type_obj_settings_list;
 
+/// Extra definition needed for \ref m_option_type_obj_presets options.
 typedef struct {
+  /// Description of the struct holding the presets.
   struct m_struct_st* in_desc;
+  /// Description of the struct that should be set by the presets.
   struct m_struct_st* out_desc;
-  void* presets; // Pointer to an arry of struct defined by in_desc
-  void* name_off; // Offset of the preset name inside the in_struct
+  /// Pointer to an array of struct defining the various presets.
+  void* presets;
+  /// Offset of the preset's name inside the in_struct.
+  void* name_off;
 } m_obj_presets_t;
+
+/// Set several fields in a struct at once.
+/** For this two struct description are used. One for the struct holding the
+ *  preset and one for the struct beeing set. Every field present in both
+ *  struct will be copied from the preset struct to the destination one.
+ *  The option priv field (\ref m_option::priv) must point to a correctly
+ *  filled \ref m_obj_presets_t.
+ */
 extern m_option_type_t m_option_type_obj_presets;
 
+/// Parse an URL into a struct.
+/** The option priv field (\ref m_option::priv) must point to a
+ *  \ref m_struct_st describing which fields of the URL must be used.
+ */
 extern m_option_type_t m_option_type_custom_url;
 
+/// Extra definition needed for \ref m_option_type_obj_params options.
 typedef struct {
-  struct m_struct_st* desc; // Fields description
-  char separator; // Field separator to use
+  /// Fields description.
+  struct m_struct_st* desc;
+  /// Field separator to use.
+  char separator;
 } m_obj_params_t;
+
+/// Parse a set of parameters.
+/** Parameters are separated by the given separator and each one
+ *  successively set a field from the struct. The option priv field
+ *  (\ref m_option::priv) must point to a \ref m_obj_params_t.
+ */
 extern m_option_type_t m_option_type_obj_params;
 
 typedef struct {
   int start;
   int end;
 } m_span_t;
+/// Ready made settings to parse a \ref m_span_t with a start-end syntax.
 extern m_obj_params_t m_span_params_def;
 
 
@@ -102,67 +162,155 @@
 
 /////////////////////////////////////////////////////////////////////////////////////////////
 
+/// Option type description
 struct m_option_type {
   char* name;
-  char* comments; // syntax desc, etc
-  unsigned int size; // size needed for a save slot
+  /// Syntax desc, etc
+  char* comments;
+  /// Size needed for the data.
+  unsigned int size;
+  /// See \ref OptionTypeFlags.
   unsigned int flags;
-
-  // parse is the only requiered function all others can be NULL
-  // If dst if non-NULL it should create/update the save slot
-  // If dst is NULL it should just test the validity of the arg if possible
-  // Src tell from where come this setting (ie cfg file, command line, playlist, ....
-  // It should return 1 if param was used, 0 if not.
-  // On error it must return 1 of the error code below
+  
+  /// Parse the data from a string.
+  /** It is the only required function, all others can be NULL.
+   * 
+   *  \param opt The option that is parsed.
+   *  \param name The full option name.
+   *  \param param The parameter to parse.
+   *  \param dst Pointer to the memory where the data should be writen.
+   *             If NULL the parameter validity should still be checked.
+   *  \param src Source of the option, see \ref OptionParserModes.
+   *  \return On error a negative value is returned, on success the number of argument
+   *          consumed. For details see \ref OptionParserReturn.
+   */
   int (*parse)(m_option_t* opt,char *name, char *param, void* dst, int src);
-  // Print back a value in human form
+  
+  /// Print back a value in string form.
+  /** \param opt The option to print.
+   *  \param val Pointer to the memory holding the data to be printed.
+   *  \return An allocated string containing the text value or (void*)-1
+   *          on error.
+   */
   char* (*print)(m_option_t* opt,  void* val);
 
-  // These 3 will be a memcpy in 50% of the case, it's called to save/restore the status of
-  // the var it's there for complex type like CONF_TYPE_FUNC*
-  // update a save slot (dst) from the current value in the prog (src)
+  /** \name
+   *  These functions are called to save/set/restore the status of the
+   *  variables. The difference between the 3 only matter for types like 
+   *  \ref m_option_type_func where 'setting' need to do more than just
+   *  copying some data.
+   */
+  //@{
+
+  /// Update a save slot (dst) from the current value in the prog (src).
+  /** \param opt The option to copy.
+   *  \param dst Pointer to the destination memory.
+   *  \param src Pointer to the source memory.
+   */
   void (*save)(m_option_t* opt,void* dst, void* src);
-  // set the current value (dst) from a save slot
+  
+  /// Set the value in the prog (dst) from a save slot.
+  /** \param opt The option to copy.
+   *  \param dst Pointer to the destination memory.
+   *  \param src Pointer to the source memory.
+   */
   void (*set)(m_option_t* opt,void* dst, void* src);
-  // Copy betewen 2 slot (if NULL and size > 0 a memcpy will be used
+
+  /// Copy the data between two save slots. If NULL and size is > 0 a memcpy will be used.
+  /** \param opt The option to copy.
+   *  \param dst Pointer to the destination memory.
+   *  \param src Pointer to the source memory.
+   */
   void (*copy)(m_option_t* opt,void* dst, void* src);
-  // Free the data allocated for a save slot if needed
+  //@}
+
+  /// Free the data allocated for a save slot.
+  /** This is only needed for dynamic types like strings.
+   *  \param dst Pointer to the data, usually a pointer that should be freed and
+   *             set to NULL.
+   */
   void (*free)(void* dst);
 };
 
+///@}
+
+/// Option description
+/** \ingroup Options
+ */
 struct m_option {
+  /// Option name.
   char *name;
-  void *p; 
+  
+  /// Reserved for higher level APIs, it shouldn't be used by parsers.
+  /** The suboption parser and func types do use it. They should instead
+   *  use the priv field but this was herited from older versions of the
+   *  config code.
+   */
+  void *p;
+  
+  /// Option type.
   m_option_type_t* type;
+  
+  /// See \ref OptionFlags.
   unsigned int flags;
-  double min,max;
-  // This used to be function pointer to hold a 'reverse to defaults' func.
-  // Nom it can be used to pass any type of extra args.
-  // Passing a 'default func' is still valid for all func based option types
-  void* priv; // Type dependent data (for all kind of extended setting)
+  
+  /// \brief Mostly usefull for numeric types, the \ref M_OPT_MIN flags must
+  /// also be set.
+  double min;
+
+  /// \brief Mostly usefull for numeric types, the \ref M_OPT_MAX flags must
+  /// also be set.
+  double max;
+  
+  /// Type dependent data (for all kind of extended setting).
+  /** This used to be function pointer to hold a 'reverse to defaults' func.
+   *  Now it can be used to pass any type of extra args needed by the parser.
+   *  Passing a 'default func' is still valid for all func based option types
+   */
+  void* priv;
 };
 
 
-//////////////////////////////// Option flags /////////////////////////////////
+/// \defgroup OptionFlags Option flags
+///@{
 
-// Option flags
+/// The option have a minimum set in \ref m_option::min.
 #define M_OPT_MIN		(1<<0)
+
+/// The option have a maximum set in \ref m_option::max.
 #define M_OPT_MAX		(1<<1)
+
+/// The option have a minimum and maximum in \ref m_option::min and \ref m_option::max.
 #define M_OPT_RANGE		(M_OPT_MIN|M_OPT_MAX)
+
+/// The option is forbidden in config files.
 #define M_OPT_NOCFG		(1<<2)
+
+/// The option is forbiden on the command line.
 #define M_OPT_NOCMD		(1<<3)
-// This option is global : it won't be saved on push and the command
-// line parser will set it when it's parsed (ie. it won't be set later)
-// e.g options : -v, -quiet
+
+/// The option is global in the \ref Config.
+/** It won't be saved on push and the command line parser will set it when
+ *  it's parsed (ie. it won't be set later)
+ *  e.g options : -v, -quiet
+ */
 #define M_OPT_GLOBAL		(1<<4)
-// Do not save this option : it won't be saved on push but the command
-// line parser will put it with it's entry (ie : it may be set later)
-// e.g options : -include
+
+/// The \ref Config won't save this option on push.
+/** It won't be saved on push but the command line parser will put it with
+ *  it's entry (ie : it may be set later)
+ *  e.g options : -include
+ */
 #define M_OPT_NOSAVE		(1<<5)
-// Emulate old behaviour by pushing the option only if it was set by the user
+
+/// \brief The \ref Config will emulate the old behaviour by pushing the
+/// option only if it was set by the user.
 #define M_OPT_OLD		(1<<6)
 
-// FIXME: backward compatibility
+/// \defgroup OldOptionFlags Backward compatibility
+///
+/// Those are kept for compatibility with older code.
+/// @{
 #define CONF_MIN		M_OPT_MIN
 #define CONF_MAX		M_OPT_MAX
 #define CONF_RANGE		M_OPT_RANGE
@@ -171,73 +319,135 @@
 #define CONF_GLOBAL		M_OPT_GLOBAL
 #define CONF_NOSAVE		M_OPT_NOSAVE
 #define CONF_OLD		M_OPT_OLD
+///@}
 
+///@}
 
-///////////////////////////// Option type flags ///////////////////////////////////
-
-// These flags are for the parsers. The description here apply to the m_config_t
-// based parsers (ie. cmd line and config file parsers)
-// Some parser will refuse option types that have some of these flags
-
-// This flag is used for the subconfig
-// When this flag is set, opt->p should point to another m_option_t array
-// Only the parse function will be called. If dst is set, it should create/update
-// an array of char* containg opt/val pairs.
-// Then the options in the child array will then be set automaticly.
-// You can only affect the way suboption are parsed.
-// Also note that suboptions may be directly accessed by using -option:subopt blah :-)
+/// \defgroup OptionTypeFlags Option type flags
+/// \ingroup OptionTypes
+///
+/// These flags are used to describe special parser capabilities or behaviour.
+///
+///@{
+
+/// Suboption parser flag.
+/** When this flag is set, m_option::p should point to another m_option
+ *  array. Only the parse function will be called. If dst is set, it should
+ *  create/update an array of char* containg opt/val pairs. The options in
+ *  the child array will then be set automatically by the \ref Config.
+ *  Also note that sub options may be directly accessed by using
+ *  -option:subopt blah.
+ */
 #define M_OPT_TYPE_HAS_CHILD		(1<<0)
-// If this flag is set the option type support option name with * at the end (used for -aa*)
-// This only affect the option name matching, the option type have to implement
-// the needed stuff.
+
+/// Wildcard matching flag.
+/** If set the option type have a use for option name ending with a *
+ *  (used for -aa*), this only affect the option name matching.
+ */
 #define M_OPT_TYPE_ALLOW_WILDCARD	(1<<1)
-// This flag indicate that the data is dynamicly allocated (opt->p point to a pointer)
-// It enable a little hack wich replace the initial value by a dynamic copy
-// in case the initial value is staticly allocated (pretty common with strings)
+
+/// Dynamic data type.
+/** This flag indicate that the data is dynamicly allocated (m_option::p point
+ *  to a pointer). It enable a little hack in the \ref Config wich replace
+ *  the initial value of such variables with a dynamic copy in case the
+ *  initial value is staticaly allocated (pretty common with strings).
+ */
 #define M_OPT_TYPE_DYNAMIC		(1<<2)
-/// If this is set the parse function doesn't directly return
-// the wanted thing. Options use this if for some reasons they have to wait
-// until the set call to be able to correctly set the target var.
-// So for those types you have to first parse and then set the target var
-// If this flag isn't set you can parse directly to the target var
-// It's used for the callback based option as the callback call may append
-// later on.
+
+/// Indirect option type.
+/** If this is set the parse function doesn't directly return
+ *  the wanted thing. Options use this if for some reasons they have to wait
+ *  until the set call to be able to correctly set the target var.
+ *  So for those types new values must first be parsed, then set to the target
+ *  var. If this flag isn't set then new values can be parsed directly to the
+ *  target var. It's used by the callback based option as the callback call
+ *  may append later on.
+ */
 #define M_OPT_TYPE_INDIRECT		(1<<3)
 
+///@}
 
 ///////////////////////////// Parser flags ////////////////////////////////////////
 
-// Config mode : some parser type behave differently depending
-// on config->mode value wich is passed in the src param of parse()
+/// \defgroup OptionParserModes Option parser modes
+/// \ingroup Options
+///
+/// Some parser behave differently depending on the mode passed in the src
+/// parameter of m_option_type::parse. For example the flag type doesn't take
+/// an argument when parsing from the command line.
+///@{
+
+/// Set when parsing from a config file.
 #define M_CONFIG_FILE 0
+/// Set when parsing command line arguments.
 #define M_COMMAND_LINE 1
 
-// Option parser error code
+///@}
+
+/// \defgroup OptionParserReturn Option parser return code
+/// \ingroup Options
+///
+/// On sucess parsers return the number of arguments consumed: 0 or 1.
+///
+/// To indicate that mplayer should exit without playing anything,
+/// parsers return M_OPT_EXIT minus the number of parameters they
+/// consumed: \ref M_OPT_EXIT or \ref M_OPT_EXIT-1.
+///
+/// On error one of the following (negative) error code is returned:
+///@{
+
+/// For use by higer level APIs when the option name is invalid.
 #define M_OPT_UNKNOWN		-1
+
+/// Returned when a parameter is needed but wasn't provided.
 #define M_OPT_MISSING_PARAM	-2
+
+/// Returned when the given parameter couldn't be parsed.
 #define M_OPT_INVALID		-3
+
+/// \brief Returned if the value is "out of range". The exact meaning may 
+/// vary from type to type.
 #define M_OPT_OUT_OF_RANGE	-4
+
+/// Returned if the parser failed for any other reason than a bad parameter.
 #define M_OPT_PARSER_ERR	-5
+
+/// Returned when MPlayer should exit. Used by various help stuff.
+/** M_OPT_EXIT must be the lowest number on this list.
+ */
 #define M_OPT_EXIT              -6
-// M_OPT_EXIT must be the lowest number on this list.
-// To indicate that mplayer should exit without playing anything,
-// a parsing function needs to return M_OPT_EXIT less the number
-// of additional command line parameters it consumed.
-// Generally it will return either M_OPT_EXIT or M_OPT_EXIT - 1.
 
-// FIXME: backward compatibility
+/// \defgroup OldOptionParserReturn Backward compatibility
+///
+/// Those are kept for compatibility with older code.
+///
+///@{
 #define ERR_NOT_AN_OPTION	M_OPT_UNKNOWN
 #define ERR_MISSING_PARAM	M_OPT_MISSING_PARAM
 #define ERR_OUT_OF_RANGE	M_OPT_OUT_OF_RANGE
 #define ERR_FUNC_ERR		M_OPT_PARSER_ERR
+///@}
 
+///@}
+
+/// Find the option matching the given name in the list.
+/** \ingroup Options
+ *  This function take the possible wildcards in account (see
+ *  \ref M_OPT_TYPE_ALLOW_WILDCARD).
+ * 
+ *  \param list Pointer to an array of \ref m_option.
+ *  \param name Name of the option.
+ *  \return The matching option or NULL.
+ */
 m_option_t* m_option_list_find(m_option_t* list,char* name);
 
+/// Helper to parse options, see \ref m_option_type::parse.
 inline static int
 m_option_parse(m_option_t* opt,char *name, char *param, void* dst, int src) {
   return opt->type->parse(opt,name,param,dst,src);
 }
 
+/// Helper to print options, see \ref m_option_type::print.
 inline static  char*
 m_option_print(m_option_t* opt,  void* val_ptr) {
   if(opt->type->print)
@@ -246,18 +456,21 @@
     return (char*)-1;
 }
 
+/// Helper around \ref m_option_type::save.
 inline static  void
 m_option_save(m_option_t* opt,void* dst, void* src) {
   if(opt->type->save)
     opt->type->save(opt,dst,src);
 }
 
+/// Helper around \ref m_option_type::set.
 inline static  void
 m_option_set(m_option_t* opt,void* dst, void* src) {
   if(opt->type->set)
     opt->type->set(opt,dst,src);
 }
 
+/// Helper around \ref m_option_type::copy.
 inline  static void
 m_option_copy(m_option_t* opt,void* dst, void* src) {
   if(opt->type->copy)
@@ -266,10 +479,13 @@
     memcpy(dst,src,opt->type->size);
 }
 
+/// Helper around \ref m_option_type::free.
 inline static void
 m_option_free(m_option_t* opt,void* dst) {
   if(opt->type->free)
     opt->type->free(dst);
 }
 
+/*@}*/
+
 #endif /* _M_OPTION_H */

Index: m_property.c
===================================================================
RCS file: /cvsroot/mplayer/main/m_property.c,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- m_property.c	23 Mar 2006 00:41:22 -0000	1.3
+++ m_property.c	24 Apr 2006 19:20:04 -0000	1.4
@@ -1,4 +1,7 @@
 
+/// \file
+/// \ingroup Properties
+
 #include "config.h"
 
 #include <stdlib.h>

Index: m_property.h
===================================================================
RCS file: /cvsroot/mplayer/main/m_property.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- m_property.h	22 Apr 2006 14:26:30 -0000	1.3
+++ m_property.h	24 Apr 2006 19:20:04 -0000	1.4
@@ -1,50 +1,136 @@
 
-// Get the current value                                                   
-#define M_PROPERTY_GET         0                                           
-// Get a string representing the current value                             
-#define M_PROPERTY_PRINT       1                                           
-// Set a new value                                                         
-#define M_PROPERTY_SET         2                                           
-// Set a new value from a string                                           
-#define M_PROPERTY_PARSE       3                                           
-// Increment the property                                                  
-#define M_PROPERTY_STEP_UP     4                                           
-// Decrement the property                                                  
-#define M_PROPERTY_STEP_DOWN   5                                           
+/// \defgroup Properties
+///
+/// Properties provide an interface to query and set the state of various
+/// things in MPlayer. The API is based on the \ref Options API like the
+/// \ref Config, but instead of using variables, properties use an ioctl like
+/// function. The function is used to perform various actions like get and set
+/// (see \ref PropertyActions).
+///@{
+
+/// \file
+
+/// \defgroup PropertyActions Property actions
+/// \ingroup Properties
+///@{
+
+/// Get the current value.
+/** \param arg Pointer to a variable of the right type.
+ */
+#define M_PROPERTY_GET         0
+
+/// Get a string representing the current value.
+/** Set the variable to a newly allocated string or NULL.
+ *  \param arg Pointer to a char* variable.
+ */
+#define M_PROPERTY_PRINT       1
+
+/// Set a new value.
+/** The variable is updated to the value actually set.
+ *  \param arg Pointer to a variable of the right type.
+ */
+#define M_PROPERTY_SET         2
+
+/// Set a new value from a string.
+/** \param arg String containing the value.
+ */
+#define M_PROPERTY_PARSE       3
+
+/// Increment the current value.
+/** The sign of the argument is also taken into account if applicable.
+ *  \param arg Pointer to a variable of the right type or NULL.
+ */
+#define M_PROPERTY_STEP_UP     4
+
+/// Decrement the current value.
+/** The sign of the argument is also taken into account if applicable.
+ *  \param arg Pointer to a variable of the right type or NULL.
+ */
+#define M_PROPERTY_STEP_DOWN   5
+
+///@}
+
+/// \defgroup PropertyActionsReturn Property actions return code
+/// \ingroup Properties
+/// \brief  Return values for the control function.
+///@{
 
-// Return values for the control function
+/// Returned on success.
 #define M_PROPERTY_OK                1
+
+/// Returned on error.
 #define M_PROPERTY_ERROR             0
-// Returned when the property can't be used, for ex something about
-// the subs while playing audio only
+
+/// \brief Returned when the property can't be used, for ex something about
+/// the subs while playing audio only
 #define M_PROPERTY_UNAVAILABLE      -1
-// Returned if the requested action is not implemented
+
+/// Returned if the requested action is not implemented.
 #define M_PROPERTY_NOT_IMPLEMENTED  -2
-// Returned when asking for a property that doesn't exist
+
+/// Returned when asking for a property that doesn't exist.
 #define M_PROPERTY_UNKNOWN          -3
-// Returned when the action can't be done (like setting the volume when edl mute)
+
+/// Returned when the action can't be done (like setting the volume when edl mute).
 #define M_PROPERTY_DISABLED         -4
 
+///@}
+
+/// \ingroup Properties
+/// \brief Property action callback.
 typedef int(*m_property_ctrl_f)(m_option_t* prop,int action,void* arg);
 
+/// Do an action on a property.
+/** \param prop The property.
+ *  \param action See \ref PropertyActions.
+ *  \param arg Argument, usually a pointer to the data type used by the property.
+ *  \return See \ref PropertyActionsReturn.
+ */
 int m_property_do(m_option_t* prop, int action, void* arg);
 
+/// Print the current value of a property.
+/** \param prop The property.
+ *  \return A newly allocated string with current value or NULL on error.
+ */
 char* m_property_print(m_option_t* prop);
 
+/// Set a property.
+/** \param prop The property.
+ *  \param txt The value to set.
+ *  \return 1 on success, 0 on error.
+ */
 int m_property_parse(m_option_t* prop, char* txt);
 
+/// Print a list of properties.
 void m_properties_print_help_list(m_option_t* list);
 
+/// Expand a property string.
+/** This function allow to print strings containing property values.
+ *  ${NAME} is expanded to the value of property NAME or an empty
+ *  string in case of error. $(NAME:STR) expand STR only if the property
+ *  NAME is available.
+ * 
+ *  \param prop_list An array of \ref m_option describing the available
+ *                   properties.
+ *  \param str The string to expand.
+ *  \return The newly allocated expanded string.
+ */
 char* m_properties_expand_string(m_option_t* prop_list,char* str);
 
 // Helpers to use MPlayer's properties
 
+/// Get an MPlayer property.
 m_option_t*  mp_property_find(char* name);
 
+/// Do an action with an MPlayer property.
 int mp_property_do(char* name,int action, void* val);
 
-// Helpers for property implementations
+/// \defgroup PropertyImplHelper Property implementation helpers
+/// \ingroup Properties
+/// \brief Helper functions for common property types.
+///@{
 
+/// Clamp a value according to \ref m_option::min and \ref m_option::max.
 #define M_PROPERTY_CLAMP(prop,val) do {                                 \
         if(((prop)->flags & M_OPT_MIN) && (val) < (prop)->min)          \
             (val) = (prop)->min;                                        \
@@ -52,37 +138,41 @@
             (val) = (prop)->max;                                        \
     } while(0)
 
-// Implement get
+/// Implement get.
 int m_property_int_ro(m_option_t* prop,int action,
                       void* arg,int var);
 
-// Implement set, get and step up/down
+/// Implement set, get and step up/down.
 int m_property_int_range(m_option_t* prop,int action,
                          void* arg,int* var);
 
-// Same but cycle
+/// Same as m_property_int_range but cycle.
 int m_property_choice(m_option_t* prop,int action,
                       void* arg,int* var);
 
-// Switch betwen min and max
+/// Switch betwen min and max.
 int m_property_flag(m_option_t* prop,int action,
                     void* arg,int* var);
 
-// Implement get, print
+/// Implement get, print.
 int m_property_float_ro(m_option_t* prop,int action,
                         void* arg,float var);
 
-// Implement set, get and step up/down
+/// Implement set, get and step up/down
 int m_property_float_range(m_option_t* prop,int action,
                            void* arg,float* var);
 
-// float with a print function which print the time in ms
+/// float with a print function which print the time in ms
 int m_property_delay(m_option_t* prop,int action,
                      void* arg,float* var);
 
-// Implement get, print
+/// Implement get, print
 int m_property_double_ro(m_option_t* prop,int action,
                          void* arg,double var);
 
-// get/print the string
+/// get/print the string
 int m_property_string_ro(m_option_t* prop,int action,void* arg, char* str);
+
+///@}
+
+///@}

Index: m_struct.c
===================================================================
RCS file: /cvsroot/mplayer/main/m_struct.c,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- m_struct.c	29 Aug 2003 21:41:03 -0000	1.4
+++ m_struct.c	24 Apr 2006 19:20:04 -0000	1.5
@@ -1,3 +1,7 @@
+
+/// \file
+/// \ingroup OptionsStruct
+
 #include "config.h"
 
 #include <stdlib.h>

Index: m_struct.h
===================================================================
RCS file: /cvsroot/mplayer/main/m_struct.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- m_struct.h	13 Aug 2003 16:29:00 -0000	1.3
+++ m_struct.h	24 Apr 2006 19:20:04 -0000	1.4
@@ -1,48 +1,108 @@
 #ifndef _M_STRUCT_H
 #define _M_STRUCT_H
 
-///////////////////// A struct setter ////////////////////////
+/// \defgroup OptionsStruct Options struct
+/// \ingroup Options
+/// An API to manipulate structs using m_option.
+///@{
+
+/// \file m_struct.h
 
 struct m_option;
 
 /// Struct definition
 typedef struct m_struct_st {
-  char* name; // For error msg and debuging
-  unsigned int size; // size of the whole struct
-  void* defaults; // Pointer to a struct filled with the default settings
-  struct m_option* fields; // settable fields
+  /// For error msg and debuging
+  char* name;
+  /// size of the whole struct
+  unsigned int size;
+  /// Pointer to a struct filled with the default settings
+  void* defaults;
+  /// Field list.
+  /** The p field of the \ref m_option struct must contain the offset
+   *  of the member in the struct (use M_ST_OFF macro for this).
+   */
+  struct m_option* fields;
 } m_struct_t;
 
-// Note : the p field of the m_option_t struct must contain the offset
-// of the member in the struct (use M_ST_OFF macro for this).
 
 // From glib.h (modified ;-)
+
+/// Get the offset of a struct field.
+/** \param struct_type Struct type.
+ *  \param member Name of the field.
+ *  \return The offset of the field in bytes.
+ */
 #define M_ST_OFF(struct_type, member)    \
     ((void*) &((struct_type*) 0)->member)
+
+/// Get a pointer to a struct field.
+/** \param struct_p Pointer to the struct.
+ *  \param struct_offset Offset of the field in the struct.
+ *  \return Pointer to the struct field.
+ */
 #define M_ST_MB_P(struct_p, struct_offset)   \
     ((void*) (struct_p) + (unsigned long) (struct_offset))
+
+/// Acces a struct field at a given offset.
+/** \param member_type Type of the field.
+ *  \param struct_p Pointer to the struct.
+ *  \param struct_offset Offset of the field in the struct.
+ *  \return The struct field at the given offset.
+ */
 #define M_ST_MB(member_type, struct_p, struct_offset)   \
     (*(member_type*) M_ST_MB_P ((struct_p), (struct_offset)))
 
 
 
-/// Allocate the struct and set it to the defaults
+/// Allocate the struct and set it to the defaults.
+/** \param st Struct definition.
+ *  \return The newly allocated object set to default.
+ */
 void*
 m_struct_alloc(m_struct_t* st);
-/// Set a field of the struct
+
+/// Set a field of the struct.
+/** \param st Struct definition.
+ *  \param obj Pointer to the struct to set.
+ *  \param field Name of the field to set.
+ *  \param param New value of the field.
+ *  \return 0 on error, 1 on success.
+ */
 int
 m_struct_set(m_struct_t* st, void* obj, char* field, char* param);
-/// Reset a field (or all if field == NULL) to defaults
+
+/// Reset a field (or all if field == NULL) to defaults.
+/** \param st Struct definiton.
+ *  \param obj Pointer to the struct to set.
+ *  \param field Name of the field to reset, if NULL all fields are reseted.
+ */
 void
 m_struct_reset(m_struct_t* st, void* obj, char* field);
-/// Create a copy of an existing struct
+
+/// Create a copy of an existing struct.
+/** \param st Struct definiton.
+ *  \param obj Pointer to the struct to copy.
+ *  \return Newly allocated copy of obj.
+ */
 void*
 m_struct_copy(m_struct_t* st, void* obj);
-/// Free an allocated struct
+
+/// Free an allocated struct.
+/** \param st Struct definiton.
+ *  \param obj Pointer to the struct to copy.
+ */
 void
 m_struct_free(m_struct_t* st, void* obj);
-/// Get a field description
+
+/// Get a field description.
+/** \param st Struct definiton.
+ *  \param f Name of the field.
+ *  \return The \ref m_option struct describing the field or NULL if not found.
+ */
 struct m_option*
 m_struct_get_field(m_struct_t* st,char* f);
 
+///@}
+
 #endif /* _M_STRUCT_H */