[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

[Diego Biurrun]

On Mon, Apr 24, 2006 at 09:20:07PM +0200, Alban Bedel CVS wrote:
> 
> --- 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.

third person singular s (3)

> +/// Profiles allow to predefine some set of options that can then
> +/// be applied later on with the internal -profile option.

a set or some sets

> +  /** This contain all options and suboptions.

third person singular s (1)

> +  /// List of the defined profiles.

"list of defined profiles" sounds better to me.

> +/// Set if another option already use the same variable.

third person singular s (1)

> +/// \defgroup Options

third person singular s (1)

> +/// m_option allow to parse, print and copy data of various types.

third person singular s (1)

> +/// \defgroup OptionTypes Options types

option types

> -// Presets are mean to be used with options struct

meant, with the

> +/** It create a NULL terminated array \ref m_obj_settings. The option priv

(1)

> +/** For this two struct description are used. One for the struct holding the

Plural s missing from description.  Is your s key stuck? ;-p

> + *  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.

dito

> +  /// Fields description.

field description

> +/** Parameters are separated by the given separator and each one
> + *  successively set a field from the struct. The option priv field

(1)

> +   *  \param dst Pointer to the memory where the data should be writen.

written

> +   *  \return On error a negative value is returned, on success the number of argument

plural s

> +   *  variables. The difference between the 3 only matter for types like 
> +   *  \ref m_option_type_func where 'setting' need to do more than just

(2)

> +   *  use the priv field but this was herited from older versions of the

inherited

> +  /// \brief Mostly usefull for numeric types, the \ref M_OPT_MIN flags must

useful

> +  /// Type dependent data (for all kind of extended setting).

plural s

> +/// The option have a minimum set in \ref m_option::min.

has

> +/// The option have a maximum set in \ref m_option::max.

has

> +/// The option have a minimum and maximum in \ref m_option::min and \ref m_option::max.

has

> +/// The option is forbiden on the command line.

forbidden

> +/// 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)

Not sure what you meant here.. "Add it to its entry?

Also: "its", not "it's".

> + *  Also note that sub options may be directly accessed by using

suboptions

> +/** If set the option type have a use for option name ending with a *

has
> + *  (used for -aa*), this only affect the option name matching.

(1)

> +/** This flag indicate that the data is dynamicly allocated (m_option::p point

(1), dynamically

> + *  to a pointer). It enable a little hack in the \ref Config wich replace

(2)

> + *  the initial value of such variables with a dynamic copy in case the
> + *  initial value is staticaly allocated (pretty common with strings).

statically

> +/// Some parser behave differently depending on the mode passed in the src

plural s, third person s

> +/// On sucess parsers return the number of arguments consumed: 0 or 1.

success

> +/// To indicate that mplayer should exit without playing anything,

MPlayer

> +/// On error one of the following (negative) error code is returned:

plural s

> +/// For use by higer level APIs when the option name is invalid.

higher

> +/// Those are kept for compatibility with older code.

These

> + *  This function take the possible wildcards in account (see

(1), into account

> +/// \brief Returned when the property can't be used, for ex something about

aw, cmon, spell it out..

> + *  \return A newly allocated string with current value or NULL on error.

with the current

> +/** This function allow to print strings containing property values.

(1)

> +  /// For error msg and debuging

debugging



Albeu, come on, you haven't used *a single* third person singular s in
that much text.  You can do better than that!

Before I sound too negative: It's excellent that you sat down and
documented all this code, three cheers :-)

Diego