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

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
This commit is contained in:
Bryce Harrington 2018-07-20 10:36:24 -04:00 committed by Mike Blumenkrantz
parent e34136ea72
commit d9515f002a
3 changed files with 69 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
src/lib/eina/eina_cow.h
View File

@ -54,11 +54,11 @@ typedef void Eina_Cow_Data;
/** /**
* @brief Instantiates a new Eina_Cow pool. * @brief Instantiates a new Eina_Cow pool.
* *
* @param name The name of this pool, used for debugging. * @param[in] name The name of this pool, used for debugging.
* @param struct_size The size of the object from this pool. * @param[in] struct_size The size of the object from this pool.
* @param step How many objects to allocate when the pool gets empty. * @param[in] step How many objects to allocate when the pool gets empty.
* @param default_value The default value returned by this pool. * @param[in] default_value The default value returned by this pool.
* @param gc Is it possible to run garbage collection on 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. * @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; 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. * @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); EAPI void eina_cow_del(Eina_Cow *cow);
/** /**
* @brief Returns an initialized pointer from the pool. * @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 * @return A pointer to the new pool instance
*/ */
EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT; EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Frees a pointer from the pool. * @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 * @note To simplify the caller code *data will point to the default
* read only state after the call to this function. * 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. * @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. * NOTE: this function is not thread safe, be careful.
*/ */
EAPI void *eina_cow_write(Eina_Cow *cow, EAPI void *eina_cow_write(Eina_Cow *cow,
const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT; const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Sets back a pointer into read only. * @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[in,out] cow The pool the pointer came from.
* @param data The pointer to which data was written to. * @param[in] dst The read only version of the pointer.
* @param needed_gc Does this pool need to be garbage collected? * @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. * 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); Eina_Bool needed_gc);
/** /**
* @brief Makes the destination contain the same thing as the source pointer. * @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[in,out] cow The pool the pointers came from.
* @param src The source of information to copy. * @param[in] dst The destination to update.
* @param[in] src The source of information to copy.
*/ */
EAPI void eina_cow_memcpy(Eina_Cow *cow, EAPI void eina_cow_memcpy(Eina_Cow *cow,
const Eina_Cow_Data * const *dst, 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. * @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. * @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. * 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 * @def EINA_COW_WRITE_BEGIN
* @brief Definition for the macro to setup a writeable pointer from a const one. * @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[in,out] Cow The Eina_Cow where the const pointer came from.
* @param Write_Type The type of the pointer you want to write to. * @param[in] 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] 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 * @since 1.8.0
* *
* Be careful: this macro opens a C scope that is expected to be closed by * 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 * @def EINA_COW_WRITE_END
* @brief Definition for the macro to close the writeable pointer. * @brief Definition for the macro to close the writeable pointer.
* @param Cow The Eina_Cow where the const pointer came from. * @param[in,out] Cow The Eina_Cow where the const pointer came from.
* @param Read The const pointer to get a writable handler from. * @param[in] 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] Write The name of the variable where to put the writeable pointer to.
* @since 1.8.0 * @since 1.8.0
* *
* Be careful: this macro close the scope opened by EINA_COW_WRITE_BEGIN(). * Be careful: this macro close the scope opened by EINA_COW_WRITE_BEGIN().

6
src/lib/eina/eina_cpu.h
View File

@ -92,7 +92,7 @@ EAPI int eina_cpu_page_size(void);
/** /**
* @brief Reverses the byte order of a 16-bit (destination) register. * @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. * @return A byte order swapped 16-bit integer.
* *
* On big endian systems, the number is converted to little endian byte order. * 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. * @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. * @return A byte order swapped 32-bit integer.
* *
* On big endian systems, the number is converted to little endian byte order. * 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. * @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. * @return A byte order swapped 64-bit integer.
* *
* On big endian systems, the number is converted to little endian byte order. * On big endian systems, the number is converted to little endian byte order.

66
src/lib/eina/eina_debug.h
View File

@ -56,10 +56,10 @@ typedef struct _Eina_Debug_Session Eina_Debug_Session;
* *
* A callback invoked when a specific packet is received. * A callback invoked when a specific packet is received.
* *
* @param session the session * @param[in,out] session the session
* @param srcid the source id * @param[in] srcid the source id
* @param buffer the packet payload data. It doesn't contain any transport information. * @param[in] buffer the packet payload data. It doesn't contain any transport information.
* @param size the packet payload size * @param[in] size the packet payload size
* *
* return true on success, false if the connection seems compromised * 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 * layer should not try to send more requests until a new connection is
* established. * established.
* *
* @param data data pointer given when registering opcodes * @param[in,out] data data pointer given when registering opcodes
* @param status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise. * @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); 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 * Dispatcher callback prototype used to override the default dispatcher of a
* session. * session.
* *
* @param session the session * @param[in,out] session the session
* @param buffer the packet received * @param[in] buffer the packet received
* *
* The given packet is the entire data received, including the header. * 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 * @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 * @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. * 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 * @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 * @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); 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. * use the default dispatcher there.
* All the packets received in this session will use this dispatcher. * All the packets received in this session will use this dispatcher.
* *
* @param session the session * @param[in,out] session the session
* @disp_cb the new dispatcher for the given 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); 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 * @brief Get the dispatcher of a specific session
* *
* @param session the session * @param[in,out] session the session
* *
* @return the session dispatcher * @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. * the correct callback according to the opcode.
* This is the default dispatcher. * This is the default dispatcher.
* *
* @param session the session * @param[in,out] session the session
* @param buffer the packet * @param[in] buffer the packet
* *
* return true on success, false if the connection seems compromised * 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 * @brief Set data to a session
* *
* @param session the session * @param[in,out] session the session
* @param data the data to set * @param[in] data the data to set
*
*/ */
EAPI void eina_debug_session_data_set(Eina_Debug_Session *session, void *data); EAPI void eina_debug_session_data_set(Eina_Debug_Session *session, void *data);
/** /**
* @brief Get the data attached to a session * @brief Get the data attached to a session
* *
* @param session the session * @param[in,out] session the session
* *
* @return the data of 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 * On the reception from the daemon, status_cb function is invoked to inform
* the requester that the opcodes can now be used. * the requester that the opcodes can now be used.
* *
* @param session the session * @param[in,out] session the session
* @param ops the operations to register * @param[in] ops the operations to register
* @param status_cb a function to call when the opcodes are received * @param[in] status_cb a function to call when the opcodes are received
* @param status_data the data to give to status_cb * @param[in] status_data the data to give to status_cb
*/ */
EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session, EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session,
const Eina_Debug_Opcode ops[], 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. * The packet will be treated by the debug thread itself.
* *
* @param session the session to use to send the packet * @param[in,out] session the session to use to send the packet
* @param dest_id the destination id to send the packet to * @param[in] dest_id the destination id to send the packet to
* @param op the opcode for this packet * @param[in] op the opcode for this packet
* @param data payload to send * @param[in] data payload to send
* @param size payload size * @param[in] size payload size
* *
* @return the number of sent bytes * @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 * @brief Add a timer
* *
* @param timeout_ms timeout in ms * @param[in] timeout_ms timeout in ms
* @param cb callback to call when the timeout is reached * @param[in] cb callback to call when the timeout is reached
* @param data user data * @param[in] data user data
* *
* @return the timer handle, NULL on error * @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 * @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 * 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. * it has already been deleted internally.