kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

More docs stuff - fix ups, rearranging, little bit o' new stuff, quieter doc generation. 

SVN revision: 11103
This commit is contained in:
ncn 2004-07-30 12:28:29 +00:00 committed by ncn
parent 49390d5f37
commit 255a0b7226
6 changed files with 236 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
legacy/ecore/Doxyfile
View File

@ -57,7 +57,7 @@ MAX_INITIALIZER_LINES = 30
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
SHOW_USED_FILES = NO
QUIET = NO
QUIET = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_FORMAT = "$file:$line: $text"

99
legacy/ecore/ecore.c.in
View File

@ -238,7 +238,10 @@ To use the library, you:
@li Load the configuration from a file. You must set the default values
first, so that the library knows the correct type of each argument.
See @ref config_basic_example.c for an example.
The following examples show how to use the Enlightened Property Library:
@li @link config_basic_example.c config_basic_example.c @endlink
@li @link config_listener_example.c config_listener_example.c @endlink
*/
/**
@ -253,16 +256,38 @@ include the @link Ecore_Data.h Ecore_Data.h @endlink to use them.
A list is a simple data type where one each piece of data points to
another piece of data.
Associated modules include the following:
Associated modules that describe the List ADT include:
@li @ref Ecore_Data_List_Creation_Group
@li @ref Ecore_Data_List_Add_Item_Group
@li @ref Ecore_Data_List_Remove_Item_Group
@li @ref Ecore_Data_List_Traverse_Group
@li @ref Ecore_Data_List_Node_Group
Examples involving lists include:
@li @link list_example.c list_example.c @endlink
@section Ecore_ADT_DList Doubly Linked List
A doubly linked list is like a linked list, only each piece of data
can also point to the piece before it.
can also point to the piece before it. In other words, you can traverse
a doubly linked list in both directions.
Associated modules that describe the DList ADT include:
@li @ref Ecore_Data_DList_Creation_Group
@li @ref Ecore_Data_DList_Add_Item_Group
@li @ref Ecore_Data_DList_Remove_Item_Group
@section Ecore_ADT_Hash Hash
A hash is an abstract data type where one value is associated with another
value. Instead of each element of the group being accessible using a
number, each element is accessed using another object.
Associated modules that describe the Hash ADT include:
@li @ref Ecore_Data_Hash_ADT_Creation_Group
@li @ref Ecore_Data_Hash_ADT_Destruction_Group
@li @ref Ecore_Data_Hash_ADT_Setting_Group
@todo Finish this.
*/
@ -324,62 +349,6 @@ state.
*/
/**
@defgroup Ecore_Data_List_Creation_Group List Creation/Destruction Functions
Functions that create, initialize and destroy Ecore_Lists.
*/
/**
@defgroup Ecore_Data_List_Add_Item_Group List Item Adding Functions
Functions that are used to add nodes to an Ecore_List.
*/
/**
@defgroup Ecore_Data_List_Remove_Item_Group List Item Removing Functions
Functions that remove nodes from an Ecore_List.
*/
/**
@defgroup Ecore_Data_List_Traverse_Group List Traversal Functions
Functions that can be used to traverse an Ecore_List.
*/
/**
@defgroup Ecore_Data_List_Node_Group List Node Functions
Functions that are used in the creation, maintenance and destruction of
Ecore_List nodes.
*/
/**
@defgroup Ecore_Config_Lib_Group Ecore Config Library Functions
Functions that are used to start up and shutdown the Ecore Configuration
Library.
*/
/**
@defgroup Ecore_Config_Property_Group Ecore Config Property Functions
Functions that retrieve or set the attributes relating to a property.
*/
/**
@defgroup Ecore_Config_Get_Group Ecore Config Retrievers
Functions that return the value of a property, based on its key.
*/
/**
@defgroup Ecore_Config_Default_Group Ecore Config Defaults
Functions that are used to set the default values of properties.
*/
/**
@defgroup Ecore_Config_Create_Group Ecore Config Create Functions
@ -387,18 +356,6 @@ Convenience functions that set default values, bounds, option values and
descriptions in one call.
*/
/**
@defgroup Ecore_Config_Set_Group Ecore Config Setters
Functions that set the value of a property.
*/
/**
@defgroup Ecore_Config_Listeners_Group Ecore Config Listeners
Functions that set and unset property listener callbacks.
*/
/**
@defgroup Ecore_Config_File_Group Ecore Config File Functions

73
legacy/ecore/src/lib/ecore/ecore_hash.c
View File

@ -29,12 +29,18 @@ static int _ecore_hash_node_init(Ecore_Hash_Node *node, void *key, void *value);
static int _ecore_hash_node_destroy(Ecore_Hash_Node *node, Ecore_Free_Cb keyd,
Ecore_Free_Cb valued);
/**
* @defgroup Ecore_Data_Hash_ADT_Creation_Group Hash Creation Functions
*
* Functions that create hash tables.
*/
/**
* @brief Create and initialize a new hash
* @param hash_func: the function for determining hash position
* @param compare: the function for comparing node keys
* @return Returns NULL on error, a new hash on success
* Creates and initializes a new hash
* @param hash_func The function for determining hash position.
* @param compare The function for comparing node keys.
* @return @c NULL on error, a new hash on success.
* @ingroup Ecore_Data_Hash_ADT_Creation_Group
*/
Ecore_Hash *ecore_hash_new(Ecore_Hash_Cb hash_func, Ecore_Compare_Cb compare)
{
@ -51,11 +57,12 @@ Ecore_Hash *ecore_hash_new(Ecore_Hash_Cb hash_func, Ecore_Compare_Cb compare)
}
/**
* @brief Initialize a hash to some sane starting values
* @param hash: the hash table to initialize
* @param hash_func: the function for hashing node keys
* @param compare: the function for comparing node keys
* @return Returns TRUE on success, FALSE on an error.
* Initializes the given hash.
* @param hash The given hash.
* @param hash_func The function used for hashing node keys.
* @param compare The function used for comparing node keys.
* @return @c TRUE on success, @c FALSE on an error.
* @ingroup Ecore_Data_Hash_ADT_Creation_Group
*/
int ecore_hash_init(Ecore_Hash *hash, Ecore_Hash_Cb hash_func, Ecore_Compare_Cb compare)
{
@ -76,10 +83,17 @@ int ecore_hash_init(Ecore_Hash *hash, Ecore_Hash_Cb hash_func, Ecore_Compare_Cb
}
/**
* @brief Set the function to destroy the keys of entries
* @param hash: the hash that this will affect
* @param function: the function that will free the node keys
* @return Returns TRUE on success, FALSE on error
* @defgroup Ecore_Data_Hash_ADT_Destruction_Group Hash Destruction Functions
*
* Functions that destroy hash tables and their contents.
*/
/**
* Sets the function to destroy the keys of the given hash.
* @param hash The given hash.
* @param function The function used to free the node keys.
* @return @c TRUE on success, @c FALSE on error.
* @ingroup Ecore_Data_Hash_ADT_Destruction_Group
*/
int ecore_hash_set_free_key(Ecore_Hash *hash, Ecore_Free_Cb function)
{
@ -94,10 +108,11 @@ int ecore_hash_set_free_key(Ecore_Hash *hash, Ecore_Free_Cb function)
}
/**
* @brief Set the function to destroy the value
* @param hash: the hash that this will affect
* @param function: the function that will free the node values
* @return Returns TRUE on success, FALSE on error
* Sets the function to destroy the values in the given hash.
* @param hash The given hash.
* @param function The function that will free the node values.
* @return @c TRUE on success, @c FALSE on error
* @ingroup Ecore_Data_Hash_ADT_Destruction_Group
*/
int ecore_hash_set_free_value(Ecore_Hash *hash, Ecore_Free_Cb function)
{
@ -112,11 +127,18 @@ int ecore_hash_set_free_value(Ecore_Hash *hash, Ecore_Free_Cb function)
}
/**
* @brief Set the key/value pair in the hash table
* @param hash: the hash table to set the the value in
* @param key: the key for this value pair
* @param value: the value corresponding with the key
* @return Returns TRUE if successful, FALSE if not
* @defgroup Ecore_Data_Hash_ADT_Setting_Group Hash Setting Functions
*
* Functions that set values in hash tables.
*/
/**
* Sets a key-value pair in the given hash table.
* @param hash The given hash table.
* @param key The key.
* @param value The value.
* @return @c TRUE if successful, @c FALSE if not.
* @ingroup Ecore_Data_Hash_ADT_Setting_Group
*/
int ecore_hash_set(Ecore_Hash *hash, void *key, void *value)
{
@ -140,9 +162,10 @@ int ecore_hash_set(Ecore_Hash *hash, void *key, void *value)
}
/**
* @brief Free the hash table and the data contained inside it
* @param hash: the hash table to destroy
* @return Returns TRUE on success, FALSE on error
* Free the hash table and the data contained inside it.
* @param hash The hash table to destroy.
* @return @c TRUE on success, @c FALSE on error.
* @ingroup Ecore_Data_Hash_ADT_Destruction_Group
*/
void ecore_hash_destroy(Ecore_Hash *hash)
{

35
legacy/ecore/src/lib/ecore/ecore_list.c
View File

@ -201,6 +201,12 @@ _ecore_list_find(void *in_list, void *in_item)
}
/* XXX: End deprecated code */
/**
@defgroup Ecore_Data_List_Creation_Group List Creation/Destruction Functions
Functions that create, initialize and destroy Ecore_Lists.
*/
/**
* Create and initialize a new list.
* @return A new initialized list on success, @c NULL on failure.
@ -345,6 +351,12 @@ int ecore_list_nodes(Ecore_List * list)
return ret;
}
/**
@defgroup Ecore_Data_List_Add_Item_Group List Item Adding Functions
Functions that are used to add nodes to an Ecore_List.
*/
/**
* Append data to the list.
* @param list The list.
@ -499,6 +511,12 @@ static int _ecore_list_insert(Ecore_List * list, Ecore_List_Node *new_node)
return TRUE;
}
/**
@defgroup Ecore_Data_List_Remove_Item_Group List Item Removing Functions
Functions that remove nodes from an Ecore_List.
*/
/**
* Remove the current item from the list.
* @param list The list to remove the current item
@ -708,6 +726,12 @@ static void *_ecore_list_remove_last(Ecore_List * list)
return ret;
}
/**
@defgroup Ecore_Data_List_Traverse_Group List Traversal Functions
Functions that can be used to traverse an Ecore_List.
*/
/**
* Make the current item the item with the given index number.
* @param list The list.
@ -1020,7 +1044,14 @@ int ecore_list_node_init(Ecore_List_Node * node)
}
/**
* Allocate and initialize a new list node
@defgroup Ecore_Data_List_Node_Group List Node Functions
Functions that are used in the creation, maintenance and destruction of
Ecore_List nodes.
*/
/**
* Allocates and initializes a new list node.
* @return A new Ecore_List_Node on success, @c NULL otherwise.
* @ingroup Ecore_Data_List_Node_Group
*/
@ -1039,7 +1070,7 @@ Ecore_List_Node *ecore_list_node_new()
}
/**
* Here we actually call the function to free the data and free the node
* Calls the function to free the data and the node.
* @param node Node to destroy.
* @param free_func Function to call if @p node points to data to free.
* @return @c TRUE.

79
legacy/ecore/src/lib/ecore_config/convenience.c
View File

@ -321,6 +321,11 @@ ecore_config_evas_font_path_apply(Evas * evas)
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 @@ ecore_config_theme_default_path_get(void)
}
/**
* 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 @@ ecore_config_theme_search_path_get(void)
}
/**
* 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 @@ ecore_config_theme_search_path_append(char *path)
}
/**
* 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 @@ ecore_config_theme_with_path_from_name_get(char *name)
}
/**
* 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 @@ ecore_config_parse_set(Ecore_Config_Prop * prop, char *arg, char *opt,
* 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

115
legacy/ecore/src/lib/ecore_config/ecore_config.c
View File

@ -30,10 +30,17 @@ static int _ecore_config_system_load(void);
static char *_ecore_config_type[] =
{ "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 @@ ecore_config_add(const char *key, char *val)
/**
* 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 @@ ecore_config_describe(const char *key, char *desc)
/**
* 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 @@ ecore_config_short_opt_set(const char *key, char short_opt)
/**
* 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 @@ ecore_config_long_opt_set(const char *key, char *long_opt)
/**
* 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)
@ -654,6 +664,12 @@ ecore_config_typed_set(const char *key, void *val, int type)
return ret;
}
/**
* @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.
@ -846,6 +862,12 @@ ecore_config_typed_default(const char *key, void *val, int type)
return ret;
}
/**
* @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.
@ -1051,6 +1073,12 @@ ecore_config_theme_default(const char *key, char *val)
return ecore_config_typed_default(key, (void *)val, PT_THM);
}
/**
* @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.
@ -1339,19 +1367,25 @@ ecore_config_init_global(char *name)
return do_init(name);
}
/**
* @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 @@ ecore_config_init(char *name)
}
/**
* 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 @@ ecore_config_shutdown(void)
}
/**
* 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 @@ _ecore_config_system_load(void)
/**
* 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)