From a4a7bc6b431fa62dce21a246658ce30cb251ecad Mon Sep 17 00:00:00 2001 From: Vincent Torri Date: Wed, 1 Sep 2010 06:45:33 +0000 Subject: [PATCH] format a bit the doc and add corner cases SVN revision: 51798 --- legacy/eina/src/lib/eina_module.c | 116 +++++++++++++++++++----------- 1 file changed, 73 insertions(+), 43 deletions(-) diff --git a/legacy/eina/src/lib/eina_module.c b/legacy/eina/src/lib/eina_module.c index 182e6bec26..656a703023 100644 --- a/legacy/eina/src/lib/eina_module.c +++ b/legacy/eina/src/lib/eina_module.c @@ -163,7 +163,7 @@ static void _dir_list_cb(const char *name, const char *path, void *data) } } -static void _dir_arch_list_db(const char *name, const char *path, void *data) +static void _dir_arch_list_cb(const char *name, const char *path, void *data) { Dir_List_Get_Cb_Data *cb_data = data; Eina_Module *m; @@ -470,9 +470,9 @@ EAPI void *eina_module_symbol_get(const Eina_Module *m, const char *symbol) * @param m The module. * @return The file name. * - * Return the file name passed in eina_module_new(). If @p m is - * @c NULL, the function returns immediatly @c NULL. The returned - * value must no be freed. + * This function returns the file name passed in eina_module_new(). If + * @p m is @c NULL, the function returns immediatly @c NULL. The + * returned value must no be freed. */ EAPI const char *eina_module_file_get(const Eina_Module *m) { @@ -481,15 +481,18 @@ EAPI const char *eina_module_file_get(const Eina_Module *m) } /** - * @brief Get the path to module with a symbol and optional subdir - * @param symbol The symbol to search for - * @param sub_dir the subdir to search in - * @return The full path of the module, or NULL in any case but success - * This returns an allocated path to the module containing @p symbol. the - * returned path must be freed. - * Searching begins in the directory containing libeina.so, and continues - * into @p sub_dir. If the symbol is not found or DL_ADDR is not supported, - * returns #NULL. + * @brief Return the path built from the location of a library and a + * given sub directory. + * + * @param symbol The symbol to search for. + * @param sub_dir The subdirectory to append. + * @return The built path on success, @c NULL otherwise. + * + * This function returns the path built by concatenating the path of + * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir + * can be @c NULL. The returned path must be freed when not used + * anymore. If the symbol is not found, or dl_addr() is not supported, + * or allocation fails, this function returns @c NULL. */ EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir) { @@ -528,16 +531,18 @@ EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir) } /** - * @brief Get the combined string of an environment variable + a subdir - * @param env The environment variable to expand - * @param sub_dir The subdir within @p env - * @return The combined path, or NULL in any case but success - * This returns the full path which is created by expanding @p env and - * adding @p sub_dir. For example: - * @code - * eina_module_environment_path_get("HOME", "/docs/somedoc.txt"); - * @endcode - * would return something like "/home/username/docs/somedoc.txt" + * @brief Return the path built from the value of an environment varialbe and a + * given sub directory. + * + * @param env The environment variable to expand. + * @param sub_dir The subdirectory to append. + * @return The built path on success, @c NULL otherwise. + * + * This function returns the path built by concatenating the value of + * the environment variable named @p env and @p sub_dir. @p sub_dir + * can be @c NULL. The returned path must be freed when not used + * anymore. If the symbol is not found, or @p env does not exist, or + * allocation fails, this function returns @c NULL. */ EAPI char *eina_module_environment_path_get(const char *env, const char *sub_dir) @@ -574,12 +579,16 @@ EAPI char *eina_module_environment_path_get(const char *env, } /** - * @brief Get an array of modules found on the directory path matching an arch type + * @brief Get an array of modules found on the directory path matching an arch type. * * @param array The array that stores the list of the modules. - * @param path The directory's path to search for modules - * @param arch the architecture string - * This returns an array of module names found in @p path which match the cpu architecture @p arch. + * @param path The directory's path to search for modules. + * @param arch The architecture string. + * + * This function adds to @p array the module names found in @p path + * which match the cpu architecture @p arch. If @p path or @p arch is + * @c NULL, the function returns immediatly @p array. @p array can be + * @c NULL. In that case, it is created with 4 elements. */ EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array, const char *path, @@ -594,20 +603,28 @@ EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array, list_get_cb_data.cb = NULL; list_get_cb_data.data = (void *)arch; - eina_file_dir_list(path, 0, &_dir_arch_list_db, &list_get_cb_data); + eina_file_dir_list(path, 0, &_dir_arch_list_cb, &list_get_cb_data); return list_get_cb_data.array; } /** - * Get a list of modules found on the directory path + * @brief Get a list of modules found on the directory path. * * @param array The array that stores the list of the modules. - * @param path The directory's path to search for modules - * @param recursive Iterate recursively on the path - * @param cb Callback function to call, if the return value of the callback is zero - * it won't be added to the list, if it is one, it will. - * @param data Data passed to the callback function + * @param path The directory's path to search for modules. + * @param recursive Iterate recursively on the path. + * @param cb Callback function to call on each module. + * @param data Data passed to the callback function. + * + * This function adds to @p array the list of modules found in + * @p path. If @p recursive is #EINA_TRUE, then recursive search is + * done. The callback @p cb is called on each file found, and @p data + * is passed to @p cb. If @p path is @c NULL, the function returns + * immediatly @p array. If the returned value of @p cb is 0, the + * module will not be added to the list, otherwise it will be added. + * @p array can be @c NULL. In that case, it is created with 4 + * elements. @p cb can be @c NULL. */ EAPI Eina_Array *eina_module_list_get(Eina_Array *array, const char *path, @@ -637,10 +654,11 @@ EAPI Eina_Array *eina_module_list_get(Eina_Array *array, * @brief Find an module in array. * * @param array The array to find the module. - * @param module The name of module to be searched; + * @param module The name of module to be searched. * - * This function finds an @p module in an @p array; - * If the element is found return the module else NULL. + * This function finds an @p module in @p array. + * If the element is found the function returns the module, else + * @c NULL is returned. */ EAPI Eina_Module * eina_module_find(const Eina_Array *array, const char *module) @@ -674,8 +692,12 @@ eina_module_find(const Eina_Array *array, const char *module) } /** - * Load every module on the list of modules - * @param array The array of modules to load + * @brief Load every module on the list of modules. + * + * @param array The array of modules to load. + * + * This function calls eina_module_load() on each element found in + * @p array. If @p array is @c NULL, this function does nothing. */ EAPI void eina_module_list_load(Eina_Array *array) { @@ -690,8 +712,12 @@ EAPI void eina_module_list_load(Eina_Array *array) } /** - * Unload every module on the list of modules - * @param array The array of modules to unload + * @brief Unload every module on the list of modules. + * + * @param array The array of modules to unload. + * + * This function calls eina_module_unload() on each element found in + * @p array. If @p array is @c NULL, this function does nothing. */ EAPI void eina_module_list_unload(Eina_Array *array) { @@ -706,8 +732,12 @@ EAPI void eina_module_list_unload(Eina_Array *array) } /** - * Helper function that iterates over the list of modules and calls - * eina_module_free on each + * @p Free every module on the list of modules. + * + * @param array The array of modules to free. + * + * This function calls eina_module_free() on each element found in + * @p array. If @p array is @c NULL, this function does nothing. */ EAPI void eina_module_list_free(Eina_Array *array) {