From b12cfbd71007521e54325fa86073705899bf5724 Mon Sep 17 00:00:00 2001 From: ncn Date: Thu, 22 Jul 2004 13:07:25 +0000 Subject: [PATCH] Spelling fix in ecore.c.in, more docs for src/lib/ecore/ecore_list.c, fix in src/lib/ecore_con/ecore_con.c and new docs for src/lib/ecore_ipc/ecore_ipc.c. SVN revision: 10962 --- legacy/ecore/ecore.c.in | 2 +- legacy/ecore/src/lib/ecore/ecore_list.c | 126 +++++++++++++-------- legacy/ecore/src/lib/ecore_con/ecore_con.c | 2 +- legacy/ecore/src/lib/ecore_ipc/ecore_ipc.c | 111 ++++++++++++------ 4 files changed, 153 insertions(+), 88 deletions(-) diff --git a/legacy/ecore/ecore.c.in b/legacy/ecore/ecore.c.in index da05ce4c26..30b2931792 100644 --- a/legacy/ecore/ecore.c.in +++ b/legacy/ecore/ecore.c.in @@ -327,7 +327,7 @@ state. /** @defgroup Ecore_Data_List_Creation_Group List Creation/Destruction Functions -Functions that create, initialize and destory Ecore_Lists. +Functions that create, initialize and destroy Ecore_Lists. */ /** diff --git a/legacy/ecore/src/lib/ecore/ecore_list.c b/legacy/ecore/src/lib/ecore/ecore_list.c index db6a07a6d5..7603f94ebd 100644 --- a/legacy/ecore/src/lib/ecore/ecore_list.c +++ b/legacy/ecore/src/lib/ecore/ecore_list.c @@ -1063,8 +1063,16 @@ int ecore_list_node_destroy(Ecore_List_Node * node, Ecore_Free_Cb free_func) } /** - * @brief Create and initialize a new list. - * @return Returns a new initialized list on success, NULL on failure. + * @defgroup Ecore_Data_DList_Creation_Group Doubly Linked List Creation/Destruction Functions + * + * Functions used to create, initialize and destroy @c Ecore_DLists. + */ + +/** + * Creates and initialises a new doubly linked list. + * @return A new initialised doubly linked list on success, @c NULL + * on failure. + * @ingroup Ecore_Data_DList_Creation_Group */ Ecore_DList *ecore_dlist_new() { @@ -1083,9 +1091,10 @@ Ecore_DList *ecore_dlist_new() } /** - * @brief Initialize a list to some sane starting values. - * @param list: the list to initialize - * @return Returns FALSE if an error occurs, TRUE if successful + * Initialises a list to some sane starting values. + * @param list The doubly linked list to initialise. + * @return @c TRUE if successful, @c FALSE if an error occurs. + * @ingroup Ecore_Data_DList_Creation_Group */ int ecore_dlist_init(Ecore_DList *list) { @@ -1099,10 +1108,9 @@ int ecore_dlist_init(Ecore_DList *list) } /** - * @brief Free a list and all of it's nodes. - * @param list: the list to be freed - * - * @return Returns no value + * Frees a doubly linked list and all of its nodes. + * @param list The doubly linked list to be freed. + * @ingroup Ecore_Data_DList_Creation_Group */ void ecore_dlist_destroy(Ecore_DList * list) { @@ -1124,10 +1132,12 @@ void ecore_dlist_destroy(Ecore_DList * list) } /** - * @brief Set the function for freeing data - * @param list: the list that will use this function when nodes are destroyed. - * @param free_func: the function that will free the key data - * @return Returns TRUE on success, FALSE on failure. + * Sets the function used for freeing data stored in a doubly linked list. + * @param list The doubly linked list that will use this function when + * nodes are destroyed. + * @param free_func The function that will free the key data + * @return @c TRUE on success, @c FALSE on failure. + * @ingroup Ecore_Data_DList_Creation_Group */ int ecore_dlist_set_free_cb(Ecore_DList * list, Ecore_Free_Cb free_func) { @@ -1137,10 +1147,9 @@ int ecore_dlist_set_free_cb(Ecore_DList * list, Ecore_Free_Cb free_func) } /** - * @brief Checks the list for any nodes. - * @param list: the list to check for nodes - * - * @return Returns TRUE if no nodes in list, FALSE if the list contains nodes + * Returns whether there is anything in the given doubly linked list. + * @param list The given doubly linked list. + * @return @c TRUE if there are nodes, @c FALSE otherwise. */ int ecore_dlist_is_empty(Ecore_DList * list) { @@ -1150,9 +1159,9 @@ int ecore_dlist_is_empty(Ecore_DList * list) } /** - * @brief Returns the number of the current node - * @param list: the list to return the number of the current node - * @return Returns the number of the current node in the list. + * Retrieves the index of the current node of the given doubly linked list. + * @param list The given doubly linked list. + * @return The index of the current node. */ inline int ecore_dlist_index(Ecore_DList * list) { @@ -1162,10 +1171,17 @@ inline int ecore_dlist_index(Ecore_DList * list) } /** - * Append data to the list. - * @param list The list to append @a data - * @param data The data to append to @a list - * @return FALSE if an error occurs, TRUE if appended successfully + * @defgroup Ecore_Data_DList_Add_Item_Group Doubly Linked List Adding Functions + * + * Functions that are used to add nodes to an Ecore_DList. + */ + +/** + * Appends data to the given doubly linked list. + * @param list The given doubly linked list. + * @param data The data to append. + * @return @c TRUE if the data is successfully appended, @c FALSE otherwise. + * @ingroup Ecore_Data_DList_Add_Item_Group */ int ecore_dlist_append(Ecore_DList * list, void *data) { @@ -1192,10 +1208,11 @@ int ecore_dlist_append(Ecore_DList * list, void *data) } /** - * Prepend data to the beginning of the list - * @param list The list to prepend @a data - * @param data The data to prepend to @a list - * @return FALSE if an error occurs, TRUE if prepended successfully + * Adds data to the very beginning of the given doubly linked list. + * @param list The given doubly linked list. + * @param data The data to prepend. + * @return @c TRUE if the data is successfully prepended, @c FALSE otherwise. + * @ingroup Ecore_Data_DList_Add_Item_Group */ int ecore_dlist_prepend(Ecore_DList * list, void *data) { @@ -1221,10 +1238,11 @@ int ecore_dlist_prepend(Ecore_DList * list, void *data) } /** - * Insert data at the current point in the list. - * @param list The list to hold the inserted @a data. - * @param data The data to insert into @a list. - * @return Returns FALSE on an error, TRUE on success + * Inserts data at the current point in the given doubly linked list. + * @param list The given doubly linked list. + * @param data The data to be inserted. + * @return @c TRUE on success, @c FALSE otherwise. + * @ingroup Ecore_Data_DList_Add_Item_Group */ int ecore_dlist_insert(Ecore_DList * list, void *data) { @@ -1264,9 +1282,16 @@ int ecore_dlist_insert(Ecore_DList * list, void *data) } /** - * @brief Remove the current item from the list. - * @param list: the list to remove the current item - * @return Returns a pointer to the removed data on success, NULL on failure. + * @defgroup Ecore_Data_DList_Remove_Item_Group Doubly Linked List Removing Functions + * + * Functions that remove nodes from an @c Ecore_DList. + */ + +/** + * Removes the current item from the given doubly linked list. + * @param list The given doubly linked list. + * @return A pointer to the removed data on success, @c NULL otherwise. + * @ingroup Ecore_Data_DList_Remove_Item_Group */ void *ecore_dlist_remove(Ecore_DList * list) { @@ -1291,9 +1316,10 @@ void *ecore_dlist_remove(Ecore_DList * list) } /** - * @brief Remove the first item from the list. - * @param list: the list to remove the current item - * @return Returns a pointer to the removed data on success, NULL on failure. + * Removes the first item from the given doubly linked list. + * @param list The given doubly linked list. + * @return A pointer to the removed data on success, @c NULL on failure. + * @ingroup Ecore_Data_DList_Remove_Item_Group */ void *ecore_dlist_remove_first(Ecore_DList * list) { @@ -1309,10 +1335,11 @@ void *ecore_dlist_remove_first(Ecore_DList * list) } /** - * @brief Remove and free the data at the current position - * @param list: the list to remove the data from - * - * @return Returns TRUE on success, FALSE on error + * Removes and frees the data at the current position in the given doubly + * linked list. + * @param list The given doubly linked list. + * @return @c TRUE on success, @c FALSE otherwise. + * @ingroup Ecore_Data_DList_Remove_Item_Group */ int ecore_dlist_remove_destroy(Ecore_DList *list) { @@ -1336,9 +1363,10 @@ static void *_ecore_dlist_remove_first(Ecore_DList *list) } /** - * @brief Remove the last item from the list - * @param list: the list to remove the last node from - * @return Returns a pointer to the removed data on success, NULL on failure. + * Removes the last item from the given doubly linked list. + * @param list The given doubly linked list. + * @return A pointer to the removed data on success, @c NULL otherwise. + * @ingroup Ecore_Data_DList_Remove_Item_Group */ void *ecore_dlist_remove_last(Ecore_DList * list) { @@ -1354,10 +1382,10 @@ void *ecore_dlist_remove_last(Ecore_DList * list) } /** - * @brief Move the current item to the index number - * @param list: the list to move the current item - * @param index: the position to move the current item - * @return Returns node at specified index on success, NULL on error + * Moves the current item to the index number in the given doubly linked list. + * @param list The given doubly linked list. + * @param index The position to move the current item + * @return The node at specified index on success, @c NULL on error. */ void *ecore_dlist_goto_index(Ecore_DList * list, int index) { diff --git a/legacy/ecore/src/lib/ecore_con/ecore_con.c b/legacy/ecore/src/lib/ecore_con/ecore_con.c index 2985a48057..3b1b077de0 100644 --- a/legacy/ecore/src/lib/ecore_con/ecore_con.c +++ b/legacy/ecore/src/lib/ecore_con/ecore_con.c @@ -325,7 +325,7 @@ ecore_con_server_add(Ecore_Con_Type compl_type, * It is used to generate the socket name when the socket * is a Unix socket. It is used as the hostname when * connecting with a TCP socket. - * @param port Number to identify socket to connect to. Used when + * @param port Number to identify the socket to connect to. Used when * generating the socket name for a Unix socket, or as the * TCP port when connecting to a TCP socket. * @param data Data to associate with the created Ecore_Con_Server diff --git a/legacy/ecore/src/lib/ecore_ipc/ecore_ipc.c b/legacy/ecore/src/lib/ecore_ipc/ecore_ipc.c index b3d10ca052..87bfa24054 100644 --- a/legacy/ecore/src/lib/ecore_ipc/ecore_ipc.c +++ b/legacy/ecore/src/lib/ecore_ipc/ecore_ipc.c @@ -191,9 +191,9 @@ int ECORE_IPC_EVENT_SERVER_DATA = 0; static int init_count = 0; static Ecore_Ipc_Server *servers = NULL; /** - * To be documented. - * - * FIXME: To be fixed. + * Initialises the Ecore IPC library. + * @return Number of times the library has been initialised without + * being shut down. */ int ecore_ipc_init(void) @@ -220,9 +220,9 @@ ecore_ipc_init(void) } /** - * To be documented. - * - * FIXME: To be fixed. + * Shuts down the Ecore IPC library. + * @return Number of times the library has been initialised without being + * shut down. */ int ecore_ipc_shutdown(void) @@ -238,9 +238,17 @@ ecore_ipc_shutdown(void) } /** - * To be documented. + * Creates an IPC server that listens for connections. * - * FIXME: To be fixed. + * For more details about the @p compl_type, @p name and @p port + * parameters, see the @ref ecore_con_server_add documentation. + * + * @param compl_type The connection type. + * @param name Name to associate with the socket used for connection. + * @param port Number to identify with socket used for connection. + * @param data Data to associate with the IPC server. + * @return New IPC server. If there is an error, @c NULL is returned. + * @todo Need to add protocol type parameter to this function. */ Ecore_Ipc_Server * ecore_ipc_server_add(Ecore_Ipc_Type compl_type, char *name, int port, const void *data) @@ -283,9 +291,20 @@ ecore_ipc_server_add(Ecore_Ipc_Type compl_type, char *name, int port, const void } /** - * To be documented. + * Creates an IPC server object to represent the IPC server listening + * on the given port. * - * FIXME: To be fixed. + * For more details about the @p compl_type, @p name and @p port + * parameters, see the @ref ecore_con_server_connect documentation. + * + * @param compl_type The IPC connection type. + * @param name Name used to determine which socket to use for the + * IPC connection. + * @param port Number used to identify the socket to use for the + * IPC connection. + * @param data Data to associate with the server. + * @return A new IPC server. @c NULL is returned on error. + * @todo Need to add protocol type parameter. */ Ecore_Ipc_Server * ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const void *data) @@ -328,9 +347,9 @@ ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const } /** - * To be documented. - * - * FIXME: To be fixed. + * Closes the connection and frees the given IPC server. + * @param svr The given IPC server. + * @return The data associated with the server when it was created. */ void * ecore_ipc_server_del(Ecore_Ipc_Server *svr) @@ -354,9 +373,9 @@ ecore_ipc_server_del(Ecore_Ipc_Server *svr) } /** - * To be documented. - * - * FIXME: To be fixed. + * Retrieves the data associated with the given IPC server. + * @param svr The given IPC server. + * @return The associated data. */ void * ecore_ipc_server_data_get(Ecore_Ipc_Server *svr) @@ -371,9 +390,9 @@ ecore_ipc_server_data_get(Ecore_Ipc_Server *svr) } /** - * To be documented. - * - * FIXME: To be fixed. + * Retrieves whether the given IPC server is currently connected. + * @param svr The given IPC server. + * @return @c 1 if the server is connected. @c 0 otherwise. */ int ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr) @@ -420,9 +439,17 @@ ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr) } /** - * To be documented. - * - * FIXME: To be fixed. + * Sends a message to the given IPC server. + * @param svr The given IPC server. + * @param major Major opcode of the message. + * @param minor Minor opcode of the message. + * @param ref Message reference number. + * @param ref_to + * @param response + * @param data The data to send as part of the message. + * @param size Length of the data, in bytes, to send. + * @return Number of bytes sent. @c 0 is returned if there is an error. + * @todo This function needs to become an IPC message. */ int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, void *data, int size) @@ -499,9 +526,18 @@ ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int } /** - * To be documented. - * - * FIXME: To be fixed. + * Sends a message to the given IPC client. + * @param cl The given IPC client. + * @param major Major opcode of the message. + * @param minor Minor opcode of the message. + * @param ref Reference number of the message. + * @param ref_to + * @param response + * @param data The data to send as part of the message. + * @param size Length of the data, in bytes, to send. + * @return The number of bytes sent. @c 0 will be returned if there is + * an error. + * @todo This function needs to become an IPC message. */ int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, void *data, int size) @@ -546,9 +582,9 @@ ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int r } /** - * To be documented. - * - * FIXME: To be fixed. + * Retrieves the IPC server that the given IPC client is connected to. + * @param cl The given IPC client. + * @return The IPC server the IPC client is connected to. */ Ecore_Ipc_Server * ecore_ipc_client_server_get(Ecore_Ipc_Client *cl) @@ -563,9 +599,10 @@ ecore_ipc_client_server_get(Ecore_Ipc_Client *cl) } /** - * To be documented. - * - * FIXME: To be fixed. + * Closes the connection and frees memory allocated to the given IPC + * client. + * @param cl The given client. + * @return Data associated with the client. */ void * ecore_ipc_client_del(Ecore_Ipc_Client *cl) @@ -590,9 +627,9 @@ ecore_ipc_client_del(Ecore_Ipc_Client *cl) } /** - * To be documented. - * - * FIXME: To be fixed. + * Sets the IPC data associated with the given IPC client to @p data. + * @param cl The given IPC client. + * @param data The data to associate with the IPC client. */ void ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data) @@ -607,9 +644,9 @@ ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data) } /** - * To be documented. - * - * FIXME: To be fixed. + * Retrieves the data that has been associated with the given IPC client. + * @param cl The given client. + * @return The data associated with the IPC client. */ void * ecore_ipc_client_data_get(Ecore_Ipc_Client *cl)