Doxygen: TODO cleanup, use @todo where needed.
Turn TODOs which should be user-visible into @todo so that Doxygen shows them in the function docs, and also on the special "Todo List" page. Those TODOs that should not be in the Doxygen docs are moved out of the /** */ comment blocks. Also fix some comments/items, and remove some obsolete ones.
This commit is contained in:
Uwe Hermann
parent
3c0839d524
commit
6b2d8d3e5c
24
datastore.c
24
datastore.c
|
|
@ -44,8 +44,8 @@ static gpointer new_chunk(struct sr_datastore **ds);
|
|||
* It is the caller's responsibility to free the allocated memory of the
|
||||
* datastore via the sr_datastore_destroy() function, if no longer needed.
|
||||
*
|
||||
* TODO: Unitsize should probably be unsigned int or uint32_t or similar.
|
||||
* TODO: This function should have a 'chunksize' parameter, and
|
||||
* @todo Unitsize should probably be unsigned int or uint32_t or similar.
|
||||
* @todo This function should have a 'chunksize' parameter, and
|
||||
* struct sr_datastore a 'chunksize' field.
|
||||
*
|
||||
* @param unitsize The unit size (>= 1) to be used for this datastore.
|
||||
|
|
@ -112,20 +112,20 @@ SR_API int sr_datastore_destroy(struct sr_datastore *ds)
|
|||
/**
|
||||
* Append some data to the specified datastore.
|
||||
*
|
||||
* TODO: More elaborate function description.
|
||||
*
|
||||
* TODO: This function should use the (not yet available) 'chunksize' field
|
||||
* @todo More elaborate function description.
|
||||
* @todo This function should use the (not yet available) 'chunksize' field
|
||||
* of struct sr_datastore (instead of hardcoding DATASTORE_CHUNKSIZE).
|
||||
* TODO: in_unitsize and probelist are unused?
|
||||
* TODO: A few of the parameters can be const.
|
||||
* TODO: Ideally, 'ds' should be unmodified upon errors.
|
||||
* @todo in_unitsize and probelist are unused?
|
||||
* @todo A few of the parameters can be const.
|
||||
* @todo Ideally, 'ds' should be unmodified upon errors.
|
||||
* @todo Should 0 be allowed as length?
|
||||
* @todo Specify/document the data format of the 'data' parameter.
|
||||
*
|
||||
* @param ds Pointer to the datastore which shall receive the data.
|
||||
* Must not be NULL.
|
||||
* @param data Pointer to the memory buffer containing the data to add.
|
||||
* Must not be NULL. TODO: Data format?
|
||||
* Must not be NULL.
|
||||
* @param length Length of the data to add (in number of bytes).
|
||||
* TODO: Should 0 be allowed as length?
|
||||
* @param in_unitsize The unit size (>= 1) of the input data.
|
||||
* @param probelist Pointer to a list of integers (probe numbers). The probe
|
||||
* numbers in this list are 1-based, i.e. the first probe
|
||||
|
|
@ -223,9 +223,9 @@ SR_API int sr_datastore_put(struct sr_datastore *ds, void *data,
|
|||
*
|
||||
* The allocated memory is guaranteed to be cleared.
|
||||
*
|
||||
* TODO: This function should use the datastore's 'chunksize' field instead
|
||||
* @todo This function should use the datastore's 'chunksize' field instead
|
||||
* of hardcoding DATASTORE_CHUNKSIZE.
|
||||
* TODO: Return int, so we can return SR_OK / SR_ERR_ARG / SR_ERR_MALLOC?
|
||||
* @todo Return int, so we can return SR_OK / SR_ERR_ARG / SR_ERR_MALLOC?
|
||||
*
|
||||
* @param ds Pointer to a variable which holds the datastore structure.
|
||||
* Must not be NULL. The contents of 'ds' are modified in-place.
|
||||
|
|
|
|||
53
session.c
53
session.c
|
|
@ -51,7 +51,7 @@ struct sr_session *session;
|
|||
/**
|
||||
* Create a new session.
|
||||
*
|
||||
* TODO: Should it use the file-global "session" variable or take an argument?
|
||||
* @todo Should it use the file-global "session" variable or take an argument?
|
||||
* The same question applies to all the other session functions.
|
||||
*
|
||||
* @return A pointer to the newly allocated session, or NULL upon errors.
|
||||
|
|
@ -86,8 +86,6 @@ SR_API int sr_session_destroy(void)
|
|||
|
||||
/* TODO: Error checks needed? */
|
||||
|
||||
/* TODO: Loop over protocol decoders and free them. */
|
||||
|
||||
g_free(session);
|
||||
session = NULL;
|
||||
|
||||
|
|
@ -101,7 +99,7 @@ static void sr_dev_close(struct sr_dev_inst *sdi)
|
|||
}
|
||||
|
||||
/**
|
||||
* Remove all the devices from the current session. TODO?
|
||||
* Remove all the devices from the current session.
|
||||
*
|
||||
* The session itself (i.e., the struct sr_session) is not free'd and still
|
||||
* exists after this function returns.
|
||||
|
|
@ -284,8 +282,6 @@ SR_API int sr_session_start(void)
|
|||
/**
|
||||
* Run the session.
|
||||
*
|
||||
* TODO: Various error checks etc.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_BUG upon errors.
|
||||
*/
|
||||
SR_API int sr_session_run(void)
|
||||
|
|
@ -416,7 +412,7 @@ static void datafeed_dump(struct sr_datafeed_packet *packet)
|
|||
*
|
||||
* Hardware drivers use this to send a data packet to the frontend.
|
||||
*
|
||||
* @param dev TODO.
|
||||
* @param sdi TODO.
|
||||
* @param packet The datafeed packet to send to the session bus.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
|
||||
|
|
@ -449,6 +445,18 @@ SR_PRIV int sr_session_send(const struct sr_dev_inst *sdi,
|
|||
return SR_OK;
|
||||
}
|
||||
|
||||
/**
|
||||
* Add an event source for a file descriptor.
|
||||
*
|
||||
* @param pollfd The GPollFD.
|
||||
* @param timeout Max time to wait before the callback is called, ignored if 0.
|
||||
* @param cb Callback function to add. Must not be NULL.
|
||||
* @param cb_data Data for the callback function. Can be NULL.
|
||||
* @param poll_object TODO.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
|
||||
* SR_ERR_MALLOC upon memory allocation errors.
|
||||
*/
|
||||
static int _sr_session_source_add(GPollFD *pollfd, int timeout,
|
||||
sr_receive_data_callback_t cb, void *cb_data, gintptr poll_object)
|
||||
{
|
||||
|
|
@ -493,7 +501,7 @@ static int _sr_session_source_add(GPollFD *pollfd, int timeout,
|
|||
}
|
||||
|
||||
/**
|
||||
* Add a event source for a file descriptor.
|
||||
* Add an event source for a file descriptor.
|
||||
*
|
||||
* @param fd The file descriptor.
|
||||
* @param events Events to check for.
|
||||
|
|
@ -518,8 +526,6 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
|
|||
/**
|
||||
* Add an event source for a GPollFD.
|
||||
*
|
||||
* TODO: More error checks etc.
|
||||
*
|
||||
* @param pollfd The GPollFD.
|
||||
* @param timeout Max time to wait before the callback is called, ignored if 0.
|
||||
* @param cb Callback function to add. Must not be NULL.
|
||||
|
|
@ -538,8 +544,6 @@ SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
|
|||
/**
|
||||
* Add an event source for a GIOChannel.
|
||||
*
|
||||
* TODO: More error checks etc.
|
||||
*
|
||||
* @param channel The GIOChannel.
|
||||
* @param events Events to poll on.
|
||||
* @param timeout Max time to wait before the callback is called, ignored if 0.
|
||||
|
|
@ -555,8 +559,7 @@ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
|
|||
GPollFD p;
|
||||
|
||||
#ifdef _WIN32
|
||||
g_io_channel_win32_make_pollfd(channel,
|
||||
events, &p);
|
||||
g_io_channel_win32_make_pollfd(channel, events, &p);
|
||||
#else
|
||||
p.fd = g_io_channel_unix_get_fd(channel);
|
||||
p.events = events;
|
||||
|
|
@ -565,7 +568,17 @@ SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
|
|||
return _sr_session_source_add(&p, timeout, cb, cb_data, (gintptr)channel);
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Remove the source belonging to the specified channel.
|
||||
*
|
||||
* @todo Add more error checks and logging.
|
||||
*
|
||||
* @param channel The channel for which the source should be removed.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
|
||||
* SR_ERR_MALLOC upon memory allocation errors, SR_ERR_BUG upon
|
||||
* internal errors.
|
||||
*/
|
||||
static int _sr_session_source_remove(gintptr poll_object)
|
||||
{
|
||||
struct source *new_sources;
|
||||
|
|
@ -613,11 +626,9 @@ static int _sr_session_source_remove(gintptr poll_object)
|
|||
return SR_OK;
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* Remove the source belonging to the specified file descriptor.
|
||||
*
|
||||
* TODO: More error checks.
|
||||
*
|
||||
* @param fd The file descriptor for which the source should be removed.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
|
||||
|
|
@ -632,8 +643,6 @@ SR_API int sr_session_source_remove(int fd)
|
|||
/**
|
||||
* Remove the source belonging to the specified poll descriptor.
|
||||
*
|
||||
* TODO: More error checks.
|
||||
*
|
||||
* @param pollfd The poll descriptor for which the source should be removed.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
|
||||
|
|
@ -645,11 +654,9 @@ SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
|
|||
return _sr_session_source_remove((gintptr)pollfd);
|
||||
}
|
||||
|
||||
/*
|
||||
/**
|
||||
* Remove the source belonging to the specified channel.
|
||||
*
|
||||
* TODO: More error checks.
|
||||
*
|
||||
* @param channel The channel for which the source should be removed.
|
||||
*
|
||||
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments, or
|
||||
|
|
|
|||
|
|
@ -334,16 +334,17 @@ SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
|
|||
* @param timestring A string containing a (decimal) time value.
|
||||
* @return The string's time value as uint64_t, in milliseconds.
|
||||
*
|
||||
* TODO: Error handling.
|
||||
* TODO: Add support for "m" (minutes) and others.
|
||||
* TODO: picoseconds?
|
||||
* TODO: Allow both lower-case and upper-case.
|
||||
* @todo Add support for "m" (minutes) and others.
|
||||
* @todo Add support for picoseconds?
|
||||
* @todo Allow both lower-case and upper-case? If no, document it.
|
||||
*/
|
||||
SR_API uint64_t sr_parse_timestring(const char *timestring)
|
||||
{
|
||||
uint64_t time_msec;
|
||||
char *s;
|
||||
|
||||
/* TODO: Error handling, logging. */
|
||||
|
||||
time_msec = strtoull(timestring, &s, 10);
|
||||
if (time_msec == 0 && s == timestring)
|
||||
return 0;
|
||||
|
|
|
|||
Loading…
Reference in New Issue