BLAHAJ
/
libsigrok
10
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Add/update Doxygen @since tags.

This commit is contained in:
Uwe Hermann 2014-05-04 20:51:05 +02:00
parent 768579456c
commit 4711724141
9 changed files with 84 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
device.c
View File

@ -83,7 +83,7 @@ SR_PRIV struct sr_channel *sr_channel_new(int index, int type,
*
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
*
* @since 0.2.0
* @since 0.3.0
*/
SR_API int sr_dev_channel_name_set(const struct sr_dev_inst *sdi,
int channelnum, const char *name)
@ -122,7 +122,7 @@ SR_API int sr_dev_channel_name_set(const struct sr_dev_inst *sdi,
* arguments, SR_ERR_ARG is returned and the channel enabled state
* remains unchanged.
*
* @since 0.2.0
* @since 0.3.0
*/
SR_API int sr_dev_channel_enable(const struct sr_dev_inst *sdi, int channelnum,
gboolean state)

18
hwdriver.c
View File

@ -440,6 +440,8 @@ static struct sr_dev_driver *drivers_list[] = {
* Return the list of supported hardware drivers.
*
* @return Pointer to the NULL-terminated list of hardware driver pointers.
*
* @since 0.1.0
*/
SR_API struct sr_dev_driver **sr_driver_list(void)
{
@ -463,6 +465,8 @@ SR_API struct sr_dev_driver **sr_driver_list(void)
* @retval SR_ERR_ARG Invalid parameter(s).
* @retval SR_ERR_BUG Internal errors.
* @retval other Another negative error code upon other errors.
*
* @since 0.2.0
*/
SR_API int sr_driver_init(struct sr_context *ctx, struct sr_dev_driver *driver)
{
@ -507,6 +511,8 @@ SR_API int sr_driver_init(struct sr_context *ctx, struct sr_dev_driver *driver)
* found (or errors were encountered). This list must be freed by the
* caller using g_slist_free(), but without freeing the data pointed
* to in the list.
*
* @since 0.2.0
*/
SR_API GSList *sr_driver_scan(struct sr_dev_driver *driver, GSList *options)
{
@ -597,6 +603,8 @@ SR_PRIV void sr_config_free(struct sr_config *src)
* @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
* interpreted as an error by the caller; merely as an indication
* that it's not applicable.
*
* @since 0.3.0
*/
SR_API int sr_config_get(const struct sr_dev_driver *driver,
const struct sr_dev_inst *sdi,
@ -636,6 +644,8 @@ SR_API int sr_config_get(const struct sr_dev_driver *driver,
* @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
* interpreted as an error by the caller; merely as an indication
* that it's not applicable.
*
* @since 0.3.0
*/
SR_API int sr_config_set(const struct sr_dev_inst *sdi,
const struct sr_channel_group *cg,
@ -663,6 +673,8 @@ SR_API int sr_config_set(const struct sr_dev_inst *sdi,
* @param sdi The device instance.
*
* @return SR_OK upon success or SR_ERR in case of error.
*
* @since 0.3.0
*/
SR_API int sr_config_commit(const struct sr_dev_inst *sdi)
{
@ -698,6 +710,8 @@ SR_API int sr_config_commit(const struct sr_dev_inst *sdi)
* @retval SR_ERR_ARG The driver doesn't know that key, but this is not to be
* interpreted as an error by the caller; merely as an indication
* that it's not applicable.
*
* @since 0.3.0
*/
SR_API int sr_config_list(const struct sr_dev_driver *driver,
const struct sr_dev_inst *sdi,
@ -723,6 +737,8 @@ SR_API int sr_config_list(const struct sr_dev_driver *driver,
*
* @return A pointer to a struct sr_config_info, or NULL if the key
* was not found.
*
* @since 0.2.0
*/
SR_API const struct sr_config_info *sr_config_info_get(int key)
{
@ -743,6 +759,8 @@ SR_API const struct sr_config_info *sr_config_info_get(int key)
*
* @return A pointer to a struct sr_config_info, or NULL if the key
* was not found.
*
* @since 0.2.0
*/
SR_API const struct sr_config_info *sr_config_info_name_get(const char *optname)
{

1
input/input.c
View File

@ -67,6 +67,7 @@ static struct sr_input_format *input_module_list[] = {
NULL,
};
/** @since 0.1.0 */
SR_API struct sr_input_format **sr_input_list(void)
{
return input_module_list;

6
libsigrok.h
View File

@ -41,9 +41,9 @@ extern "C" {
*
* The correct way to get/use the libsigrok API functions is:
*
@code{.c}
#include <libsigrok/libsigrok.h>
@endcode
* @code{.c}
* #include <libsigrok/libsigrok.h>
* @endcode
*/
/*

2
log.c
View File

@ -164,7 +164,7 @@ SR_API char *sr_log_logdomain_get(void)
*
* @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
*
* @since 0.1.0
* @since 0.3.0
*/
SR_API int sr_log_callback_set(sr_log_callback cb, void *cb_data)
{

5
output/output.c
View File

@ -73,11 +73,13 @@ static struct sr_output_format *output_module_list[] = {
NULL,
};
/** @since 0.1.0 */
SR_API struct sr_output_format **sr_output_list(void)
{
return output_module_list;
}
/** @since 0.3.0 */
SR_API struct sr_output *sr_output_new(struct sr_output_format *of,
GHashTable *params, const struct sr_dev_inst *sdi)
{
@ -95,12 +97,14 @@ SR_API struct sr_output *sr_output_new(struct sr_output_format *of,
return o;
}
/** @since 0.3.0 */
SR_API int sr_output_send(struct sr_output *o,
const struct sr_datafeed_packet *packet, GString **out)
{
return o->format->receive(o, packet, out);
}
/** @since 0.3.0 */
SR_API int sr_output_free(struct sr_output *o)
{
int ret;
@ -113,5 +117,4 @@ SR_API int sr_output_free(struct sr_output *o)
return ret;
}
/** @} */

32
session.c
View File

@ -71,6 +71,8 @@ struct sr_session *session;
*
* @retval NULL Error.
* @retval other A pointer to the newly allocated session.
*
* @since 0.1.0
*/
SR_API struct sr_session *sr_session_new(void)
{
@ -93,6 +95,8 @@ SR_API struct sr_session *sr_session_new(void)
*
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*
* @since 0.1.0
*/
SR_API int sr_session_destroy(void)
{
@ -121,6 +125,8 @@ SR_API int sr_session_destroy(void)
*
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*
* @since 0.1.0
*/
SR_API int sr_session_dev_remove_all(void)
{
@ -145,6 +151,8 @@ SR_API int sr_session_dev_remove_all(void)
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_BUG No session exists.
*
* @since 0.2.0
*/
SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi)
{
@ -209,6 +217,8 @@ SR_API int sr_session_dev_add(const struct sr_dev_inst *sdi)
*
* @retval SR_OK Success.
* @retval SR_ERR Invalid argument.
*
* @since 0.3.0
*/
SR_API int sr_session_dev_list(GSList **devlist)
{
@ -228,6 +238,8 @@ SR_API int sr_session_dev_list(GSList **devlist)
*
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*
* @since 0.1.0
*/
SR_API int sr_session_datafeed_callback_remove_all(void)
{
@ -251,6 +263,8 @@ SR_API int sr_session_datafeed_callback_remove_all(void)
*
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*
* @since 0.3.0
*/
SR_API int sr_session_datafeed_callback_add(sr_datafeed_callback cb, void *cb_data)
{
@ -340,6 +354,8 @@ static int sr_session_iteration(gboolean block)
*
* @retval SR_OK Success.
* @retval SR_ERR Error occured.
*
* @since 0.1.0
*/
SR_API int sr_session_start(void)
{
@ -386,6 +402,8 @@ SR_API int sr_session_start(void)
*
* @retval SR_OK Success.
* @retval SR_ERR_BUG Error occured.
*
* @since 0.1.0
*/
SR_API int sr_session_run(void)
{
@ -470,6 +488,8 @@ SR_PRIV int sr_session_stop_sync(void)
*
* @retval SR_OK Success.
* @retval SR_ERR_BUG No session exists.
*
* @since 0.1.0
*/
SR_API int sr_session_stop(void)
{
@ -638,6 +658,8 @@ static int _sr_session_source_add(GPollFD *pollfd, int timeout,
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*
* @since 0.3.0
*/
SR_API int sr_session_source_add(int fd, int events, int timeout,
sr_receive_data_callback cb, void *cb_data)
@ -661,6 +683,8 @@ SR_API int sr_session_source_add(int fd, int events, int timeout,
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*
* @since 0.3.0
*/
SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
sr_receive_data_callback cb, void *cb_data)
@ -681,6 +705,8 @@ SR_API int sr_session_source_add_pollfd(GPollFD *pollfd, int timeout,
* @retval SR_OK Success.
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
*
* @since 0.3.0
*/
SR_API int sr_session_source_add_channel(GIOChannel *channel, int events,
int timeout, sr_receive_data_callback cb, void *cb_data)
@ -765,6 +791,8 @@ static int _sr_session_source_remove(gintptr poll_object)
* @retval SR_ERR_ARG Invalid argument
* @retval SR_ERR_MALLOC Memory allocation error.
* @retval SR_ERR_BUG Internal error.
*
* @since 0.3.0
*/
SR_API int sr_session_source_remove(int fd)
{
@ -779,6 +807,8 @@ SR_API int sr_session_source_remove(int fd)
* @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.
*
* @since 0.2.0
*/
SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
{
@ -794,6 +824,8 @@ SR_API int sr_session_source_remove_pollfd(GPollFD *pollfd)
* @retval SR_ERR_ARG Invalid argument.
* @retval SR_ERR_MALLOC Memory allocation error.
* @return SR_ERR_BUG Internal error.
*
* @since 0.2.0
*/
SR_API int sr_session_source_remove_channel(GIOChannel *channel)
{

6
session_file.c
View File

@ -232,6 +232,8 @@ SR_API int sr_session_load(const char *filename)
* @retval SR_OK Success
* @retval SR_ERR_ARG Invalid arguments
* @retval SR_ERR Other errors
*
* @since 0.2.0
*/
SR_API int sr_session_save(const char *filename, const struct sr_dev_inst *sdi,
unsigned char *buf, int unitsize, int units)
@ -286,6 +288,8 @@ SR_API int sr_session_save(const char *filename, const struct sr_dev_inst *sdi,
* @retval SR_OK Success
* @retval SR_ERR_ARG Invalid arguments
* @retval SR_ERR Other errors
*
* @since 0.3.0
*/
SR_API int sr_session_save_init(const char *filename, uint64_t samplerate,
char **channels)
@ -377,6 +381,8 @@ SR_API int sr_session_save_init(const char *filename, uint64_t samplerate,
* @retval SR_OK Success
* @retval SR_ERR_ARG Invalid arguments
* @retval SR_ERR Other errors
*
* @since 0.3.0
*/
SR_API int sr_session_append(const char *filename, unsigned char *buf,
int unitsize, int units)

18
strutil.c
View File

@ -228,6 +228,8 @@ SR_PRIV int sr_atof_ascii(const char *str, float *ret)
* @return A g_try_malloc()ed string representation of the samplerate value,
* or NULL upon errors. The caller is responsible to g_free() the
* memory.
*
* @since 0.2.0
*/
SR_API char *sr_si_string_u64(uint64_t x, const char *unit)
{
@ -268,6 +270,8 @@ SR_API char *sr_si_string_u64(uint64_t x, const char *unit)
* @return A g_try_malloc()ed string representation of the samplerate value,
* or NULL upon errors. The caller is responsible to g_free() the
* memory.
*
* @since 0.1.0
*/
SR_API char *sr_samplerate_string(uint64_t samplerate)
{
@ -285,6 +289,8 @@ SR_API char *sr_samplerate_string(uint64_t samplerate)
* @return A g_try_malloc()ed string representation of the frequency value,
* or NULL upon errors. The caller is responsible to g_free() the
* memory.
*
* @since 0.1.0
*/
SR_API char *sr_period_string(uint64_t frequency)
{
@ -328,6 +334,8 @@ SR_API char *sr_period_string(uint64_t frequency)
* @return A g_try_malloc()ed string representation of the voltage value,
* or NULL upon errors. The caller is responsible to g_free() the
* memory.
*
* @since 0.2.0
*/
SR_API char *sr_voltage_string(uint64_t v_p, uint64_t v_q)
{
@ -377,6 +385,8 @@ SR_API char *sr_voltage_string(uint64_t v_p, uint64_t v_q)
* a trigger value set in 'triggerstring' are NULL, the other entries
* contain the respective trigger type which is requested for the
* respective channel (e.g. "r", "c", and so on).
*
* @since 0.2.0
*/
SR_API char **sr_parse_triggerstring(const struct sr_dev_inst *sdi,
const char *triggerstring)
@ -463,6 +473,8 @@ SR_API char **sr_parse_triggerstring(const struct sr_dev_inst *sdi,
* @param size Pointer to uint64_t which will contain the string's size value.
*
* @return SR_OK upon success, SR_ERR upon errors.
*
* @since 0.1.0
*/
SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
{
@ -528,6 +540,8 @@ SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
* @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.
*
* @since 0.1.0
*/
SR_API uint64_t sr_parse_timestring(const char *timestring)
{
@ -554,6 +568,7 @@ SR_API uint64_t sr_parse_timestring(const char *timestring)
return time_msec;
}
/** @since 0.1.0 */
SR_API gboolean sr_parse_boolstring(const char *boolstr)
{
if (!boolstr)
@ -568,6 +583,7 @@ SR_API gboolean sr_parse_boolstring(const char *boolstr)
return FALSE;
}
/** @since 0.2.0 */
SR_API int sr_parse_period(const char *periodstr, uint64_t *p, uint64_t *q)
{
char *s;
@ -600,7 +616,7 @@ SR_API int sr_parse_period(const char *periodstr, uint64_t *p, uint64_t *q)
return SR_OK;
}
/** @since 0.2.0 */
SR_API int sr_parse_voltage(const char *voltstr, uint64_t *p, uint64_t *q)
{
char *s;