summaryrefslogtreecommitdiff
path: root/src/lib/eina
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2018-07-20 10:36:24 -0400
committerMike Blumenkrantz <zmike@samsung.com>2018-07-20 10:36:24 -0400
commitd9515f002a69d6f1daec6bdda2fbcb139943364a (patch)
treed0de33b604ff2b0bc8b0b7c1bcdb288e754494fd /src/lib/eina
parente34136ea7223cb161af782e8da949a15c3317b57 (diff)
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
Diffstat (limited to 'src/lib/eina')
-rw-r--r--src/lib/eina/eina_cow.h60
-rw-r--r--src/lib/eina/eina_cpu.h6
-rw-r--r--src/lib/eina/eina_debug.h66
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;
54/** 54/**
55 * @brief Instantiates a new Eina_Cow pool. 55 * @brief Instantiates a new Eina_Cow pool.
56 * 56 *
57 * @param name The name of this pool, used for debugging. 57 * @param[in] name The name of this pool, used for debugging.
58 * @param struct_size The size of the object from this pool. 58 * @param[in] struct_size The size of the object from this pool.
59 * @param step How many objects to allocate when the pool gets empty. 59 * @param[in] step How many objects to allocate when the pool gets empty.
60 * @param default_value The default value returned by this pool. 60 * @param[in] default_value The default value returned by this pool.
61 * @param gc Is it possible to run garbage collection on this pool. 61 * @param[in] gc Is it possible to run garbage collection on this pool.
62 * @return A valid new Eina_Cow, or @c NULL on error. 62 * @return A valid new Eina_Cow, or @c NULL on error.
63 */ 63 */
64EAPI 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; 64EAPI 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
66/** 66/**
67 * @brief Destroys an Eina_Cow pool and all the allocated memory. 67 * @brief Destroys an Eina_Cow pool and all the allocated memory.
68 * 68 *
69 * @param cow The pool to destroy 69 * @param[in] cow The pool to destroy
70 */ 70 */
71EAPI void eina_cow_del(Eina_Cow *cow); 71EAPI void eina_cow_del(Eina_Cow *cow);
72 72
73/** 73/**
74 * @brief Returns an initialized pointer from the pool. 74 * @brief Returns an initialized pointer from the pool.
75 * @param cow The pool to take things from. 75 *
76 * @param[in] cow The pool to take things from.
76 * @return A pointer to the new pool instance 77 * @return A pointer to the new pool instance
77 */ 78 */
78EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT; 79EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
79 80
80/** 81/**
81 * @brief Frees a pointer from the pool. 82 * @brief Frees a pointer from the pool.
82 * @param cow The pool to gave back memory to. 83 *
83 * @param data The data to give back. 84 * @param[in,out] cow The pool to gave back memory to.
85 * @param[in] data The data to give back.
84 * 86 *
85 * @note To simplify the caller code *data will point to the default 87 * @note To simplify the caller code *data will point to the default
86 * read only state after the call to this function. 88 * 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);
89 91
90/** 92/**
91 * @brief Gets a writeable pointer from a const pointer. 93 * @brief Gets a writeable pointer from a const pointer.
92 * @param cow The pool the pointer came from. 94 *
93 * @param src The pointer you want to write to. 95 * @param[in,out] cow The pool the pointer came from.
96 * @param[in] src The pointer you want to write to.
94 * 97 *
95 * NOTE: this function is not thread safe, be careful. 98 * NOTE: this function is not thread safe, be careful.
96 */ 99 */
97EAPI void *eina_cow_write(Eina_Cow *cow, 100EAPI void *eina_cow_write(Eina_Cow *cow,
98 const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT; 101 const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
102
99/** 103/**
100 * @brief Sets back a pointer into read only. 104 * @brief Sets back a pointer into read only.
101 * @param cow The pool the pointer came from. 105 *
102 * @param dst The read only version of the pointer. 106 * @param[in,out] cow The pool the pointer came from.
103 * @param data The pointer to which data was written to. 107 * @param[in] dst The read only version of the pointer.
104 * @param needed_gc Does this pool need to be garbage collected? 108 * @param[in] data The pointer to which data was written to.
109 * @param[in] needed_gc Does this pool need to be garbage collected?
105 * 110 *
106 * NOTE: this function is not thread safe, be careful. 111 * NOTE: this function is not thread safe, be careful.
107 */ 112 */
@@ -111,9 +116,10 @@ EAPI void eina_cow_done(Eina_Cow *cow,
111 Eina_Bool needed_gc); 116 Eina_Bool needed_gc);
112/** 117/**
113 * @brief Makes the destination contain the same thing as the source pointer. 118 * @brief Makes the destination contain the same thing as the source pointer.
114 * @param cow The pool the pointers came from. 119 *
115 * @param dst The destination to update. 120 * @param[in,out] cow The pool the pointers came from.
116 * @param src The source of information to copy. 121 * @param[in] dst The destination to update.
122 * @param[in] src The source of information to copy.
117 */ 123 */
118EAPI void eina_cow_memcpy(Eina_Cow *cow, 124EAPI void eina_cow_memcpy(Eina_Cow *cow,
119 const Eina_Cow_Data * const *dst, 125 const Eina_Cow_Data * const *dst,
@@ -121,7 +127,8 @@ EAPI void eina_cow_memcpy(Eina_Cow *cow,
121 127
122/** 128/**
123 * @brief Tries to find entries that have the same content and update them. 129 * @brief Tries to find entries that have the same content and update them.
124 * @param cow The cow to try to compact. 130 *
131 * @param[in,out] cow The cow to try to compact.
125 * @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was. 132 * @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was.
126 * 133 *
127 * There is no guaranty in the time it will require, but should remain low. 134 * 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);
133/** 140/**
134 * @def EINA_COW_WRITE_BEGIN 141 * @def EINA_COW_WRITE_BEGIN
135 * @brief Definition for the macro to setup a writeable pointer from a const one. 142 * @brief Definition for the macro to setup a writeable pointer from a const one.
136 * @param Cow The Eina_Cow where the const pointer came from. 143 *
137 * @param Read The const pointer to get a writable handler from. 144 * @param[in,out] Cow The Eina_Cow where the const pointer came from.
138 * @param Write_Type The type of the pointer you want to write to. 145 * @param[in] Read The const pointer to get a writable handler from.
139 * @param Write The name of the variable where to put the writeable pointer to. 146 * @param[in] Write_Type The type of the pointer you want to write to.
147 * @param[in] Write The name of the variable where to put the writeable pointer to.
140 * @since 1.8.0 148 * @since 1.8.0
141 * 149 *
142 * Be careful: this macro opens a C scope that is expected to be closed by 150 * 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);
152/** 160/**
153 * @def EINA_COW_WRITE_END 161 * @def EINA_COW_WRITE_END
154 * @brief Definition for the macro to close the writeable pointer. 162 * @brief Definition for the macro to close the writeable pointer.
155 * @param Cow The Eina_Cow where the const pointer came from. 163 * @param[in,out] Cow The Eina_Cow where the const pointer came from.
156 * @param Read The const pointer to get a writable handler from. 164 * @param[in] Read The const pointer to get a writable handler from.
157 * @param Write The name of the variable where to put the writeable pointer to. 165 * @param[in] Write The name of the variable where to put the writeable pointer to.
158 * @since 1.8.0 166 * @since 1.8.0
159 * 167 *
160 * Be careful: this macro close the scope opened by EINA_COW_WRITE_BEGIN(). 168 * 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);
92/** 92/**
93 * @brief Reverses the byte order of a 16-bit (destination) register. 93 * @brief Reverses the byte order of a 16-bit (destination) register.
94 * 94 *
95 * @param x The binary word to swap 95 * @param[in] x The binary word to swap
96 * @return A byte order swapped 16-bit integer. 96 * @return A byte order swapped 16-bit integer.
97 * 97 *
98 * On big endian systems, the number is converted to little endian byte order. 98 * 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);
103/** 103/**
104 * @brief Reverses the byte order of a 32-bit (destination) register. 104 * @brief Reverses the byte order of a 32-bit (destination) register.
105 * 105 *
106 * @param x The binary word to swap 106 * @param[in] x The binary word to swap
107 * @return A byte order swapped 32-bit integer. 107 * @return A byte order swapped 32-bit integer.
108 * 108 *
109 * On big endian systems, the number is converted to little endian byte order. 109 * 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);
114/** 114/**
115 * @brief Reverses the byte order of a 64-bit (destination) register. 115 * @brief Reverses the byte order of a 64-bit (destination) register.
116 * 116 *
117 * @param x The binary word to swap 117 * @param[in] x The binary word to swap
118 * @return A byte order swapped 64-bit integer. 118 * @return A byte order swapped 64-bit integer.
119 * 119 *
120 * On big endian systems, the number is converted to little endian byte order. 120 * 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;
56 * 56 *
57 * A callback invoked when a specific packet is received. 57 * A callback invoked when a specific packet is received.
58 * 58 *
59 * @param session the session 59 * @param[in,out] session the session
60 * @param srcid the source id 60 * @param[in] srcid the source id
61 * @param buffer the packet payload data. It doesn't contain any transport information. 61 * @param[in] buffer the packet payload data. It doesn't contain any transport information.
62 * @param size the packet payload size 62 * @param[in] size the packet payload size
63 * 63 *
64 * return true on success, false if the connection seems compromised 64 * return true on success, false if the connection seems compromised
65 */ 65 */
@@ -75,8 +75,8 @@ typedef Eina_Bool (*Eina_Debug_Cb)(Eina_Debug_Session *session, int srcid, void
75 * layer should not try to send more requests until a new connection is 75 * layer should not try to send more requests until a new connection is
76 * established. 76 * established.
77 * 77 *
78 * @param data data pointer given when registering opcodes 78 * @param[in,out] data data pointer given when registering opcodes
79 * @param status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise. 79 * @param[in] status EINA_TRUE if opcodes have been received from the daemon, EINA_FALSE otherwise.
80 */ 80 */
81typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status); 81typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status);
82 82
@@ -86,8 +86,8 @@ typedef void (*Eina_Debug_Opcode_Status_Cb)(void *data, Eina_Bool status);
86 * Dispatcher callback prototype used to override the default dispatcher of a 86 * Dispatcher callback prototype used to override the default dispatcher of a
87 * session. 87 * session.
88 * 88 *
89 * @param session the session 89 * @param[in,out] session the session
90 * @param buffer the packet received 90 * @param[in] buffer the packet received
91 * 91 *
92 * The given packet is the entire data received, including the header. 92 * The given packet is the entire data received, including the header.
93 * 93 *
@@ -167,7 +167,7 @@ EAPI void eina_debug_disable(void);
167/** 167/**
168 * @brief Connect to the local daemon 168 * @brief Connect to the local daemon
169 * 169 *
170 * @param is_master true if the application is a debugger. EINA_FALSE otherwise. 170 * @param[in] is_master true if the application is a debugger. EINA_FALSE otherwise.
171 * 171 *
172 * @return the session on success or NULL otherwise 172 * @return the session on success or NULL otherwise
173 */ 173 */
@@ -178,7 +178,7 @@ EAPI Eina_Debug_Session *eina_debug_local_connect(Eina_Bool is_master);
178 * 178 *
179 * This function connects to localhost:port. 179 * This function connects to localhost:port.
180 * 180 *
181 * @param port the port to connect to 181 * @param[in] port the port to connect to
182 * 182 *
183 * @return the session on success or NULL otherwise 183 * @return the session on success or NULL otherwise
184 */ 184 */
@@ -187,8 +187,7 @@ EAPI Eina_Debug_Session *eina_debug_remote_connect(int port);
187/** 187/**
188 * @brief Terminate the session 188 * @brief Terminate the session
189 * 189 *
190 * @param session the session to terminate 190 * @param[in,out] session the session to terminate
191 *
192 */ 191 */
193EAPI void eina_debug_session_terminate(Eina_Debug_Session *session); 192EAPI void eina_debug_session_terminate(Eina_Debug_Session *session);
194 193
@@ -199,15 +198,15 @@ EAPI void eina_debug_session_terminate(Eina_Debug_Session *session);
199 * use the default dispatcher there. 198 * use the default dispatcher there.
200 * All the packets received in this session will use this dispatcher. 199 * All the packets received in this session will use this dispatcher.
201 * 200 *
202 * @param session the session 201 * @param[in,out] session the session
203 * @disp_cb the new dispatcher for the given session 202 * @param[in] disp_cb the new dispatcher for the given session
204 */ 203 */
205EAPI void eina_debug_session_dispatch_override(Eina_Debug_Session *session, Eina_Debug_Dispatch_Cb disp_cb); 204EAPI void eina_debug_session_dispatch_override(Eina_Debug_Session *session, Eina_Debug_Dispatch_Cb disp_cb);
206 205
207/** 206/**
208 * @brief Get the dispatcher of a specific session 207 * @brief Get the dispatcher of a specific session
209 * 208 *
210 * @param session the session 209 * @param[in,out] session the session
211 * 210 *
212 * @return the session dispatcher 211 * @return the session dispatcher
213 */ 212 */
@@ -220,8 +219,8 @@ EAPI Eina_Debug_Dispatch_Cb eina_debug_session_dispatch_get(Eina_Debug_Session *
220 * the correct callback according to the opcode. 219 * the correct callback according to the opcode.
221 * This is the default dispatcher. 220 * This is the default dispatcher.
222 * 221 *
223 * @param session the session 222 * @param[in,out] session the session
224 * @param buffer the packet 223 * @param[in] buffer the packet
225 * 224 *
226 * return true on success, false if the connection seems compromised 225 * return true on success, false if the connection seems compromised
227 */ 226 */
@@ -230,16 +229,15 @@ EAPI Eina_Bool eina_debug_dispatch(Eina_Debug_Session *session, void *buffer);
230/** 229/**
231 * @brief Set data to a session 230 * @brief Set data to a session
232 * 231 *
233 * @param session the session 232 * @param[in,out] session the session
234 * @param data the data to set 233 * @param[in] data the data to set
235 *
236 */ 234 */
237EAPI void eina_debug_session_data_set(Eina_Debug_Session *session, void *data); 235EAPI void eina_debug_session_data_set(Eina_Debug_Session *session, void *data);
238 236
239/** 237/**
240 * @brief Get the data attached to a session 238 * @brief Get the data attached to a session
241 * 239 *
242 * @param session the session 240 * @param[in,out] session the session
243 * 241 *
244 * @return the data of the session 242 * @return the data of the session
245 */ 243 */
@@ -254,10 +252,10 @@ EAPI void *eina_debug_session_data_get(Eina_Debug_Session *session);
254 * On the reception from the daemon, status_cb function is invoked to inform 252 * On the reception from the daemon, status_cb function is invoked to inform
255 * the requester that the opcodes can now be used. 253 * the requester that the opcodes can now be used.
256 * 254 *
257 * @param session the session 255 * @param[in,out] session the session
258 * @param ops the operations to register 256 * @param[in] ops the operations to register
259 * @param status_cb a function to call when the opcodes are received 257 * @param[in] status_cb a function to call when the opcodes are received
260 * @param status_data the data to give to status_cb 258 * @param[in] status_data the data to give to status_cb
261 */ 259 */
262EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session, 260EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session,
263 const Eina_Debug_Opcode ops[], 261 const Eina_Debug_Opcode ops[],
@@ -268,11 +266,11 @@ EAPI void eina_debug_opcodes_register(Eina_Debug_Session *session,
268 * 266 *
269 * The packet will be treated by the debug thread itself. 267 * The packet will be treated by the debug thread itself.
270 * 268 *
271 * @param session the session to use to send the packet 269 * @param[in,out] session the session to use to send the packet
272 * @param dest_id the destination id to send the packet to 270 * @param[in] dest_id the destination id to send the packet to
273 * @param op the opcode for this packet 271 * @param[in] op the opcode for this packet
274 * @param data payload to send 272 * @param[in] data payload to send
275 * @param size payload size 273 * @param[in] size payload size
276 * 274 *
277 * @return the number of sent bytes 275 * @return the number of sent bytes
278 */ 276 */
@@ -281,9 +279,9 @@ EAPI int eina_debug_session_send(Eina_Debug_Session *session, int dest_id, int o
281/** 279/**
282 * @brief Add a timer 280 * @brief Add a timer
283 * 281 *
284 * @param timeout_ms timeout in ms 282 * @param[in] timeout_ms timeout in ms
285 * @param cb callback to call when the timeout is reached 283 * @param[in] cb callback to call when the timeout is reached
286 * @param data user data 284 * @param[in] data user data
287 * 285 *
288 * @return the timer handle, NULL on error 286 * @return the timer handle, NULL on error
289 */ 287 */
@@ -292,7 +290,7 @@ EAPI Eina_Debug_Timer *eina_debug_timer_add(unsigned int timeout_ms, Eina_Debug_
292/** 290/**
293 * @brief Delete a timer 291 * @brief Delete a timer
294 * 292 *
295 * @param timer the timer to delete 293 * @param[in,out] timer the timer to delete
296 * 294 *
297 * If the timer reaches the end and has not be renewed, trying to delete it will lead to a crash, as 295 * If the timer reaches the end and has not be renewed, trying to delete it will lead to a crash, as
298 * it has already been deleted internally. 296 * it has already been deleted internally.