Enlightenment CVS committal
Author : ncn
Project : e17
Module : libs/ecore
Dir : e17/libs/ecore/src/lib/ecore_config
Modified Files:
convenience.c ecore_config.c
Log Message:
More docs stuff - fix ups, rearranging, little bit o' new stuff, quieter doc
generation.
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_config/convenience.c,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -3 -r1.20 -r1.21
--- convenience.c 27 Jul 2004 21:27:25 -0000 1.20
+++ convenience.c 30 Jul 2004 12:28:29 -0000 1.21
@@ -321,6 +321,11 @@
return ECORE_CONFIG_ERR_SUCC;
}
+/**
+ * Retrieves the default theme search path.
+ *
+ * @return The default theme search path.
+ */
char *
ecore_config_theme_default_path_get(void)
{
@@ -354,12 +359,15 @@
}
/**
- * Returns the search path used to find themes. This is specified by a user in the
- * property "/e/themes/search_path". If the property is not set the path defaults to
- * "/usr/local/share/<app_name>/themes/|~/.e/apps/<app_name>/themes".
- * Note: This should be called after ecore_config_load() to allow a users overriding
- * search path to be read.
- * @return The search path, or NULL if there is no memory left.
+ * Retrieves the search path used to find themes.
+ *
+ * The search path is stored in the property "/e/themes/search_path". If
+ * the property has not been set, the default path used is
+ * "/usr/local/share/<app_name>/themes|~/.e/apps/<app_name>/themes".
+ * See @ref ecore_config_theme_default_path_get for more information about
+ * the default path.
+ *
+ * @return The search path. @c NULL is returned if there is no memory left.
*/
char *
ecore_config_theme_search_path_get(void)
@@ -381,16 +389,18 @@
}
/**
- * Adds to the search path used to find themes. The current path is found and
- * searches for occurrences of the appending item. If this item is not found it
- * is appended to the search path wich is then saved back into the property
- * "/e/themes/search_path".
- * Note: This should be called after ecore_config_load() to allow a users
- * overriding the default search path to be read.
- * @return On success ECORE_CONFIG_ERR_SUCC, on fail ECORE_CONFIG_ERR_FAIL
- * (appending item already in search path) or on NULL being passed in
- * ECORE_CONFIG_ERR_NODATA
-*/
+ * Adds the given path to the search path used to find themes.
+ *
+ * If the search path is successfully, the new search path will be saved
+ * into the property "/e/themes/search_path". Therefore, this function
+ * should be called @b after @ref ecore_config_load to allow a user to
+ * override the default search path.
+ *
+ * @param path The given
+ * @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_FAIL
+ * will be returned if @p path already exists in the search path.
+ * @c ECORE_CONFIG_ERR_FAIL is returned if @p path is @c NULL.
+ */
int
ecore_config_theme_search_path_append(char *path)
{
@@ -422,12 +432,15 @@
}
/**
- * Get a theme files full path, as it is found according to the search path.
- * The theme searched for is @name (e.g. "winter").
- * The search path is defined by ecore_config_theme_search_path_get().
- * @param name The theme name to search for.
- * @return A full path to the theme on sucess, or NULL on failure (no key specified or
- * no theme matching that name could be found).
+ * Retrieve a theme file's full path.
+ *
+ * The search path for theme files is given by @ref
+ * ecore_config_theme_search_path_get .
+ *
+ * @param name The name of the theme.
+ * @return A full path to the theme on success. @c NULL will be returned
+ * if @p name is @c NULL or no theme matching the given name could
+ * be found.
*/
char *
ecore_config_theme_with_path_from_name_get(char *name)
@@ -471,12 +484,16 @@
}
/**
- * Get a theme files full path, as it is found according to the search path.
- * The theme searched for is stored in the property @p key.
- * The search path is defined by ecore_config_theme_search_path_get().
- * @param key The property containing the theme name to search for.
- * @return A full path to the theme on sucess, or NULL on failure (no key specified or
- * no theme matching that name could be found).
+ * Retrieves the full path to the theme file of the theme stored in the
+ * given property.
+ *
+ * The search path for themes is given by @ref
+ * ecore_config_theme_search_path_get .
+ *
+ * @param key The given property.
+ * @return A full path to the theme on success, or @c NULL on failure.
+ * This function will fail if no key is specified or not theme
+ * matching that given by the property @p key could be found.
*/
char *
ecore_config_theme_with_path_get(const char *key)
@@ -543,9 +560,9 @@
* Parse the arguments set by @ref ecore_app_args_set and set properties
* accordingly.
*
- * @return ECORE_CONFIG_PARSE_CONTINUE if successful.
- * ECORE_CONFIG_PARSE_EXIT is returned if an unrecognised option
- * is found. ECORE_CONFIG_PARSE_HELP is returned if help was
+ * @return @c ECORE_CONFIG_PARSE_CONTINUE if successful.
+ * @c ECORE_CONFIG_PARSE_EXIT is returned if an unrecognised option
+ * is found. @c ECORE_CONFIG_PARSE_HELP is returned if help was
* displayed.
*/
int
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_config/ecore_config.c,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -3 -r1.42 -r1.43
--- ecore_config.c 30 Jul 2004 10:01:44 -0000 1.42
+++ ecore_config.c 30 Jul 2004 12:28:29 -0000 1.43
@@ -31,9 +31,16 @@
{ "undefined", "integer", "float", "string", "colour", "theme" };
/**
+ * @defgroup Ecore_Config_Property_Group Ecore Config Property Functions
+ *
+ * Functions that retrieve or set the attributes relating to a property.
+ */
+
+/**
* Removes the given property from the local configuration and destroys it.
- * @param e Property to destroy.
- * @return @c NULL
+ * @param e Property to destroy.
+ * @return @c NULL
+ * @ingroup Ecore_Config_Property_Group
*/
Ecore_Config_Prop *
ecore_config_dst(Ecore_Config_Prop * e)
@@ -555,10 +562,10 @@
/**
* Sets the description field of the indicated property.
- * @param key The property key.
- * @param desc Description string.
- * @note The description string is copied for the property's use. You can
- * free @p desc once this function is called.
+ * @param key The property key.
+ * @param desc Description string.
+ * @note The description string is copied for the property's use. You can
+ * free @p desc once this function is called.
* @ingroup Ecore_Config_Property_Group
*/
int
@@ -574,11 +581,12 @@
/**
* Set the short option character of a property.
- * @param key The property key.
- * @param short_opt Character used to indicate the value of a property
- * given on the command line.
- * @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
- * is returned if the property does not exist.
+ * @param key The property key.
+ * @param short_opt Character used to indicate the value of a property
+ * given on the command line.
+ * @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
+ * is returned if the property does not exist.
+ * @ingroup Ecore_Config_Property_Group
*/
int
ecore_config_short_opt_set(const char *key, char short_opt)
@@ -593,11 +601,12 @@
/**
* Set the long option string of the property.
- * @param key The property key.
- * @param long_opt String used to indicate the value of a property given
- * on the command line.
- * @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
- * is returned if the property does not exist.
+ * @param key The property key.
+ * @param long_opt String used to indicate the value of a property given
+ * on the command line.
+ * @return @c ECORE_CONFIG_ERR_SUCC on success. @c ECORE_CONFIG_ERR_NODATA
+ * is returned if the property does not exist.
+ * @ingroup Ecore_Config_Property_Group
*/
int
ecore_config_long_opt_set(const char *key, char *long_opt)
@@ -614,10 +623,11 @@
/**
* Sets the indicated property to the given value and type.
- * @param key The property key.
- * @param val A pointer to the value to set the property to.
- * @param type The type of the property.
- * @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
+ * @param key The property key.
+ * @param val A pointer to the value to set the property to.
+ * @param type The type of the property.
+ * @return @c ECORE_CONFIG_ERR_SUCC if the property is set successfully.
+ * @ingroup Ecore_Config_Property_Group
*/
int
ecore_config_typed_set(const char *key, void *val, int type)
@@ -655,6 +665,12 @@
}
/**
+ * @defgroup Ecore_Config_Set_Group Ecore Config Setters
+ *
+ * Functions that set the value of a property.
+ */
+
+/**
* Sets the indicated property to the value indicated by @a val.
* @param key The property key.
* @param val String representation of value to set.
@@ -847,6 +863,12 @@
}
/**
+ * @defgroup Ecore_Config_Default_Group Ecore Config Defaults
+ *
+ * Functions that are used to set the default values of properties.
+ */
+
+/**
* Sets the indicated property if it has not already been set or loaded.
* @param key The property key.
* @param val Default value of the key.
@@ -1052,6 +1074,12 @@
}
/**
+ * @defgroup Ecore_Config_Listeners_Group Ecore Config Listeners
+ *
+ * Functions that set and unset property listener callbacks.
+ */
+
+/**
* Adds a callback function to the list of functions called when a property
* changes.
* @param name Name of the callback.
@@ -1340,18 +1368,24 @@
}
/**
+ * @defgroup Ecore_Config_App_Lib_Group Ecore Config App Library Functions
+ *
+ * Functions that are used to start up and shutdown the Enlightened
+ * Property Library when used directly by an application.
+ */
+
+/**
* Initializes the Enlightened Property Library.
*
- * This function (or @ref ecore_config_system_init)
- * must be run before any other function in the
- * Enlightened Property Library, even if you have run @ref ecore_init .
- * The name given is used to determine the default configuration to
- * load.
+ * Either this function or @ref ecore_config_system_init must be run
+ * before any other function in the Enlightened Property Library, even
+ * if you have run @ref ecore_init . The name given is used to
+ * determine the default configuration to load.
*
* @param name Application name
* @return @c ECORE_CONFIG_ERR_SUCC if the library is successfully set up.
* @c ECORE_CONFIG_ERR_FAIL otherwise.
- * @ingroup Ecore_Config_Lib_Group
+ * @ingroup Ecore_Config_App_Lib_Group
*/
int
ecore_config_init(char *name)
@@ -1381,9 +1415,9 @@
}
/**
- * Frees memory and shuts down the library.
- * @return @c ECORE_CONFIG_ERR_IGNORED
- * @ingroup Ecore_Config_Lib_Group
+ * Frees memory and shuts down the library for an application.
+ * @return @c ECORE_CONFIG_ERR_IGNORED .
+ * @ingroup Ecore_Config_App_Lib_Group
*/
int
ecore_config_shutdown(void)
@@ -1392,18 +1426,25 @@
}
/**
- * Initializes the Enlightened Property Library (call from libraries i.e. ewl - NOT
applications).
+ * @defgroup Ecore_Config_Lib_Lib_Group Ecore Config Library Functions
*
- * This function (or ecore_config_init)
+ * Functions that are used to start up and shutdown the Enlightened
+ * Property Library when used directly by an application.
+ */
+
+/**
+ * Initializes the Enlightened Property Library.
+ *
+ * This function is meant to be run from other programming libraries.
+ * It should not be called from applications.
+ *
+ * This function (or @ref ecore_config_init )
* must be run before any other function in the
* Enlightened Property Library, even if you have run @ref ecore_init .
- * The name given is used to determine the default configuration to
- * load.
*
- * @param name Application name
* @return @c ECORE_CONFIG_ERR_SUCC if the library is successfully set up.
* @c ECORE_CONFIG_ERR_FAIL otherwise.
- * @ingroup Ecore_Config_Lib_Group
+ * @ingroup Ecore_Config_Lib_Lib_Group
*/
int
ecore_config_system_init(void)
@@ -1477,9 +1518,9 @@
/**
- * Frees memory and shuts down the library (call from libraries i.e. ewl - NOT
applications).
+ * Frees memory and shuts down the library for other programming libraries.
* @return @c ECORE_CONFIG_ERR_IGNORED
- * @ingroup Ecore_Config_Lib_Group
+ * @ingroup Ecore_Config_Lib_Lib_Group
*/
int
ecore_config_system_shutdown(void)
-------------------------------------------------------
This SF.Net email is sponsored by OSTG. Have you noticed the changes on
Linux.com, ITManagersJournal and NewsForge in the past few weeks? Now,
one more big change to announce. We are now OSTG- Open Source Technology
Group. Come see the changes on the new OSTG site. www.ostg.com
_______________________________________________
enlightenment-cvs mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/enlightenment-cvs
