From: Uwe Hermann <redacted>
Date: Sun, 4 May 2014 18:51:05 +0000 (+0200)
Subject: Add/update Doxygen @since tags.
X-Git-Tag: libsigrok-0.3.0~8
X-Git-Url: http://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=4711724141f9073af8b2493c3fc6a643d5c77cbe

Add/update Doxygen @since tags.
---

diff --git a/device.c b/device.c
index 055c3719..f87bb66d 100644
--- a/device.c
+++ b/device.c
@@ -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)
diff --git a/hwdriver.c b/hwdriver.c
index dea9e0c4..aca6d1e1 100644
--- a/hwdriver.c
+++ b/hwdriver.c
@@ -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)
 {
diff --git a/input/input.c b/input/input.c
index 40886df9..d22b3734 100644
--- a/input/input.c
+++ b/input/input.c
@@ -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;
diff --git a/libsigrok.h b/libsigrok.h
index 4a81b96d..65d1490f 100644
--- a/libsigrok.h
+++ b/libsigrok.h
@@ -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
  */
 
 /*
diff --git a/log.c b/log.c
index 44bd49c5..8ab46b32 100644
--- a/log.c
+++ b/log.c
@@ -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)
 {
diff --git a/output/output.c b/output/output.c
index 941678ec..4cf78f60 100644
--- a/output/output.c
+++ b/output/output.c
@@ -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;
 }
 
-
 /** @} */
diff --git a/session.c b/session.c
index 263185c1..0540942f 100644
--- a/session.c
+++ b/session.c
@@ -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)
 {
diff --git a/session_file.c b/session_file.c
index e8ad2107..880ef6db 100644
--- a/session_file.c
+++ b/session_file.c
@@ -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)
diff --git a/strutil.c b/strutil.c
index 01bdbd11..e63f12e1 100644
--- a/strutil.c
+++ b/strutil.c
@@ -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;