From d9515f002a69d6f1daec6bdda2fbcb139943364a Mon Sep 17 00:00:00 2001 From: Bryce Harrington Date: Fri, 20 Jul 2018 10:36:24 -0400 Subject: [PATCH] eina: Add doxygen in/out tags for cow, cpu, and debug Reviewers: devilhorns Reviewed By: devilhorns Subscribers: cedric, #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6642 --- src/lib/eina/eina_cow.h | 60 ++++++++++++++++++++--------------- src/lib/eina/eina_cpu.h | 6 ++-- src/lib/eina/eina_debug.h | 66 +++++++++++++++++++-------------------- 3 files changed, 69 insertions(+), 63 deletions(-) diff --git a/src/lib/eina/eina_cow.h b/src/lib/eina/eina_cow.h index 347a8c5c62..db2acd5fc0 100644 --- a/src/lib/eina/eina_cow.h +++ b/src/lib/eina/eina_cow.h @@ -54,11 +54,11 @@ typedef void Eina_Cow_Data; /** * @brief Instantiates a new Eina_Cow pool. * - * @param name The name of this pool, used for debugging. - * @param struct_size The size of the object from this pool. - * @param step How many objects to allocate when the pool gets empty. - * @param default_value The default value returned by this pool. - * @param gc Is it possible to run garbage collection on this pool. + * @param[in] name The name of this pool, used for debugging. + * @param[in] struct_size The size of the object from this pool. + * @param[in] step How many objects to allocate when the pool gets empty. + * @param[in] default_value The default value returned by this pool. + * @param[in] gc Is it possible to run garbage collection on this pool. * @return A valid new Eina_Cow, or @c NULL on error. */ EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value, Eina_Bool gc) EINA_WARN_UNUSED_RESULT; @@ -66,21 +66,23 @@ EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned /** * @brief Destroys an Eina_Cow pool and all the allocated memory. * - * @param cow The pool to destroy + * @param[in] cow The pool to destroy */ EAPI void eina_cow_del(Eina_Cow *cow); /** * @brief Returns an initialized pointer from the pool. - * @param cow The pool to take things from. + * + * @param[in] cow The pool to take things from. * @return A pointer to the new pool instance */ EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT; /** * @brief Frees a pointer from the pool. - * @param cow The pool to gave back memory to. - * @param data The data to give back. + * + * @param[in,out] cow The pool to gave back memory to. + * @param[in] data The data to give back. * * @note To simplify the caller code *data will point to the default * read only state after the call to this function. @@ -89,19 +91,22 @@ EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data); /** * @brief Gets a writeable pointer from a const pointer. - * @param cow The pool the pointer came from. - * @param src The pointer you want to write to. + * + * @param[in,out] cow The pool the pointer came from. + * @param[in] src The pointer you want to write to. * * NOTE: this function is not thread safe, be careful. */ EAPI void *eina_cow_write(Eina_Cow *cow, const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT; + /** * @brief Sets back a pointer into read only. - * @param cow The pool the pointer came from. - * @param dst The read only version of the pointer. - * @param data The pointer to which data was written to. - * @param needed_gc Does this pool need to be garbage collected? + * + * @param[in,out] cow The pool the pointer came from. + * @param[in] dst The read only version of the pointer. + * @param[in] data The pointer to which data was written to. + * @param[in] needed_gc Does this pool need to be garbage collected? * * NOTE: this function is not thread safe, be careful. */ @@ -111,9 +116,10 @@ EAPI void eina_cow_done(Eina_Cow *cow, Eina_Bool needed_gc); /** * @brief Makes the destination contain the same thing as the source pointer. - * @param cow The pool the pointers came from. - * @param dst The destination to update. - * @param src The source of information to copy. + * + * @param[in,out] cow The pool the pointers came from. + * @param[in] dst The destination to update. + * @param[in] src The source of information to copy. */ EAPI void eina_cow_memcpy(Eina_Cow *cow, const Eina_Cow_Data * const *dst, @@ -121,7 +127,8 @@ EAPI void eina_cow_memcpy(Eina_Cow *cow, /** * @brief Tries to find entries that have the same content and update them. - * @param cow The cow to try to compact. + * + * @param[in,out] cow The cow to try to compact. * @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was. * * There is no guaranty in the time it will require, but should remain low. @@ -133,10 +140,11 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow); /** * @def EINA_COW_WRITE_BEGIN * @brief Definition for the macro to setup a writeable pointer from a const one. - * @param Cow The Eina_Cow where the const pointer came from. - * @param Read The const pointer to get a writable handler from. - * @param Write_Type The type of the pointer you want to write to. - * @param Write The name of the variable where to put the writeable pointer to. + * + * @param[in,out] Cow The Eina_Cow where the const pointer came from. + * @param[in] Read The const pointer to get a writable handler from. + * @param[in] Write_Type The type of the pointer you want to write to. + * @param[in] Write The name of the variable where to put the writeable pointer to. * @since 1.8.0 * * Be careful: this macro opens a C scope that is expected to be closed by @@ -152,9 +160,9 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow); /** * @def EINA_COW_WRITE_END * @brief Definition for the macro to close the writeable pointer. - * @param Cow The Eina_Cow where the const pointer came from. - * @param Read The const pointer to get a writable handler from. - * @param Write The name of the variable where to put the writeable pointer to. + * @param[in,out] Cow The Eina_Cow where the const pointer came from. + * @param[in] Read The const pointer to get a writable handler from. + * @param[in] Write The name of the variable where to put the writeable pointer to. * @since 1.8.0 * * Be careful: this macro close the scope opened by EINA_COW_WRITE_BEGIN(). diff --git a/src/lib/eina/eina_cpu.h b/src/lib/eina/eina_cpu.h index 05de0fa8f5..6235b7b939 100644 --- a/src/lib/eina/eina_cpu.h +++ b/src/lib/eina/eina_cpu.h @@ -92,7 +92,7 @@ EAPI int eina_cpu_page_size(void); /** * @brief Reverses the byte order of a 16-bit (destination) register. * - * @param x The binary word to swap + * @param[in] x The binary word to swap * @return A byte order swapped 16-bit integer. * * On big endian systems, the number is converted to little endian byte order. @@ -103,7 +103,7 @@ static inline unsigned short eina_swap16(unsigned short x); /** * @brief Reverses the byte order of a 32-bit (destination) register. * - * @param x The binary word to swap + * @param[in] x The binary word to swap * @return A byte order swapped 32-bit integer. * * On big endian systems, the number is converted to little endian byte order. @@ -114,7 +114,7 @@ static inline unsigned int eina_swap32(unsigned int x); /** * @brief Reverses the byte order of a 64-bit (destination) register. * - * @param x The binary word to swap + * @param[in] x The binary word to swap * @return A byte order swapped 64-bit integer. * * On big endian systems, the number is converted to little endian byte order. diff --git a/src/lib/eina/eina_debug.h b/src/lib/eina/eina_debug.h index 132f598875..77e8165eab 100644 --- a/src/lib/eina/eina_debug.h +++ b/src/lib/eina/eina_debug.h @@ -56,10 +56,10 @@ typedef struct _Eina_Debug_Session Eina_Debug_Session; * * A callback invoked when a specific packet is received. * - * @param session the session - * @param srcid the source id - * @param buffer the packet payload data. It doesn't contain any transport information. - * @param size the packet payload size + * @param[in,out] session the session + * @param[in] srcid the source id + * @param[in] buffer the packet payload data. It doesn't contain any transport information. + * @param[in] size the packet payload size * * return true on success, false if the connection seems compromised */ @@ -75,8 +75,8 @@ typedef Eina_Bool (*Eina_Debug_Cb)(Eina_Debug_Session *session, int srcid, void * layer should not try to send more requests until a new connection is * established. * - * @param data data pointer given when registering opcodes - * @param status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise. + * @param[in,out] data data pointer given when registering opcodes + * @param[in] status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise. */ typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status); @@ -86,8 +86,8 @@ typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status); * Dispatcher callback prototype used to override the default dispatcher of a * session. * - * @param session the session - * @param buffer the packet received + * @param[in,out] session the session + * @param[in] buffer the packet received * * The given packet is the entire data received, including the header. * @@ -167,7 +167,7 @@ EAPI void eina_debug_disable(void); /** * @brief Connect to the local daemon * - * @param is_master true if the application is a debugger. EINA_FALSE otherwise. + * @param[in] is_master true if the application is a debugger. EINA_FALSE otherwise. * * @return the session on success or NULL otherwise */ @@ -178,7 +178,7 @@ EAPI Eina_Debug_Session *eina_debug_local_connect(Eina_Bool is_master); * * This function connects to localhost:port. * - * @param port the port to connect to + * @param[in] port the port to connect to * * @return the session on success or NULL otherwise */ @@ -187,8 +187,7 @@ EAPI Eina_Debug_Session *eina_debug_remote_connect(int port); /** * @brief Terminate the session * - * @param session the session to terminate - * + * @param[in,out] session the session to terminate */ EAPI void eina_debug_session_terminate(Eina_Debug_Session *session); @@ -199,15 +198,15 @@ EAPI void eina_debug_session_terminate(Eina_Debug_Session *session); * use the default dispatcher there. * All the packets received in this session will use this dispatcher. * - * @param session the session - * @disp_cb the new dispatcher for the given session + * @param[in,out] session the session + * @param[in] disp_cb the new dispatcher for the given session */ EAPI void eina_debug_session_dispatch_override(Eina_Debug_Session *session, Eina_Debug_Dispatch_Cb disp_cb); /** * @brief Get the dispatcher of a specific session * - * @param session the session + * @param[in,out] session the session * * @return the session dispatcher */ @@ -220,8 +219,8 @@ EAPI Eina_Debug_Dispatch_Cb eina_debug_session_dispatch_get(Eina_Debug_Session * * the correct callback according to the opcode. * This is the default dispatcher. * - * @param session the session - * @param buffer the packet + * @param[in,out] session the session + * @param[in] buffer the packet * * return true on success, false if the connection seems compromised */ @@ -230,16 +229,15 @@ EAPI Eina_Bool eina_debug_dispatch(Eina_Debug_Session *session, void *buffer); /** * @brief Set data to a session * - * @param session the session - * @param data the data to set - * + * @param[in,out] session the session + * @param[in] data the data to set */ EAPI void eina_debug_session_data_set(Eina_Debug_Session *session, void *data); /** * @brief Get the data attached to a session * - * @param session the session + * @param[in,out] session the session * * @return the data of the session */ @@ -254,10 +252,10 @@ EAPI void *eina_debug_session_data_get(Eina_Debug_Session *session); * On the reception from the daemon, status_cb function is invoked to inform * the requester that the opcodes can now be used. * - * @param session the session - * @param ops the operations to register - * @param status_cb a function to call when the opcodes are received - * @param status_data the data to give to status_cb + * @param[in,out] session the session + * @param[in] ops the operations to register + * @param[in] status_cb a function to call when the opcodes are received + * @param[in] status_data the data to give to status_cb */ EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session, const Eina_Debug_Opcode ops[], @@ -268,11 +266,11 @@ EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session, * * The packet will be treated by the debug thread itself. * - * @param session the session to use to send the packet - * @param dest_id the destination id to send the packet to - * @param op the opcode for this packet - * @param data payload to send - * @param size payload size + * @param[in,out] session the session to use to send the packet + * @param[in] dest_id the destination id to send the packet to + * @param[in] op the opcode for this packet + * @param[in] data payload to send + * @param[in] size payload size * * @return the number of sent bytes */ @@ -281,9 +279,9 @@ EAPI int eina_debug_session_send(Eina_Debug_Session *session, int dest_id, int o /** * @brief Add a timer * - * @param timeout_ms timeout in ms - * @param cb callback to call when the timeout is reached - * @param data user data + * @param[in] timeout_ms timeout in ms + * @param[in] cb callback to call when the timeout is reached + * @param[in] data user data * * @return the timer handle, NULL on error */ @@ -292,7 +290,7 @@ EAPI Eina_Debug_Timer *eina_debug_timer_add(unsigned int timeout_ms, Eina_Debug_ /** * @brief Delete a timer * - * @param timer the timer to delete + * @param[in,out] timer the timer to delete * * If the timer reaches the end and has not be renewed, trying to delete it will lead to a crash, as * it has already been deleted internally.