From: Uwe Hermann <redacted>
Date: Fri, 3 May 2013 12:45:49 +0000 (+0200)
Subject: Doxygen: Add @since markers to API functions.
X-Git-Tag: libsigrokdecode-0.2.0~6
X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=commitdiff_plain;h=8c664ca2d7b4faffa7b3dbeb3b9e491976c24eee;hp=f11e9498c83d4b27ffc1029f6dbd7ef871953aca

Doxygen: Add @since markers to API functions.

Also, document the functions in version.c.
---

diff --git a/controller.c b/controller.c
index 23f529d..e023b71 100644
--- a/controller.c
+++ b/controller.c
@@ -130,6 +130,8 @@ extern SRD_PRIV PyTypeObject srd_logic_type;
  *         Upon Python errors, return SRD_ERR_PYTHON. If the sigrok decoders
  *         directory cannot be accessed, return SRD_ERR_DECODERS_DIR.
  *         If not enough memory could be allocated, return SRD_ERR_MALLOC.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_init(const char *path)
 {
@@ -180,6 +182,8 @@ SRD_API int srd_init(const char *path)
  * any successful srd_init() calls in between, is not allowed.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_exit(void)
 {
@@ -211,6 +215,8 @@ SRD_API int srd_exit(void)
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
  * @private
+ *
+ * @since 0.1.0
  */
 SRD_PRIV int srd_decoder_searchpath_add(const char *path)
 {
@@ -284,6 +290,8 @@ SRD_PRIV int srd_decoder_searchpath_add(const char *path)
  * @param options A GHashTable of options to set.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_inst_option_set(struct srd_decoder_inst *di,
 		GHashTable *options)
@@ -427,6 +435,8 @@ static gint compare_probe_id(const struct srd_probe *a, const char *probe_id)
  *                   arranged in this order.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
 		GHashTable *new_probes)
@@ -517,6 +527,8 @@ SRD_API int srd_inst_probe_set_all(struct srd_decoder_inst *di,
  *
  * @return Pointer to a newly allocated struct srd_decoder_inst, or
  *         NULL in case of failure.
+ *
+ * @since 0.1.0
  */
 SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
 		GHashTable *options)
@@ -592,6 +604,8 @@ SRD_API struct srd_decoder_inst *srd_inst_new(const char *decoder_id,
  * @param di_to The instance on top of which di_from will be stacked.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_inst_stack(struct srd_decoder_inst *di_from,
 		struct srd_decoder_inst *di_to)
@@ -621,6 +635,8 @@ SRD_API int srd_inst_stack(struct srd_decoder_inst *di_from,
  * @param inst_id The instance ID to be found.
  *
  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
+ *
+ * @since 0.1.0
  */
 SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id)
 {
@@ -653,6 +669,8 @@ SRD_API struct srd_decoder_inst *srd_inst_find_by_id(const char *inst_id)
  * @return Pointer to struct srd_decoder_inst, or NULL if not found.
  *
  * @private
+ *
+ * @since 0.1.0
  */
 SRD_PRIV struct srd_decoder_inst *srd_inst_find_by_obj(const GSList *stack,
 		const PyObject *obj)
@@ -724,6 +742,8 @@ SRD_PRIV int srd_inst_start(struct srd_decoder_inst *di, PyObject *args)
  * @return SRD_OK upon success, a (negative) error code otherwise.
  *
  * @private
+ *
+ * @since 0.1.0
  */
 SRD_PRIV int srd_inst_decode(uint64_t start_samplenum,
 		const struct srd_decoder_inst *di, const uint8_t *inbuf,
@@ -837,6 +857,8 @@ SRD_PRIV void srd_inst_free_all(GSList *stack)
  * @param samplerate The samplerate of the incoming feed.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
 {
@@ -882,6 +904,8 @@ SRD_API int srd_session_start(int num_probes, int unitsize, uint64_t samplerate)
  * @param inbuflen Length in bytes of the buffer.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_session_send(uint64_t start_samplenum, const uint8_t *inbuf,
 		uint64_t inbuflen)
@@ -913,6 +937,8 @@ SRD_API int srd_session_send(uint64_t start_samplenum, const uint8_t *inbuf,
  *                    callback per output type can be registered.
  * @param cb The function to call. Must not be NULL.
  * @param cb_data Private data for the callback function. Can be NULL.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_pd_output_callback_add(int output_type,
 		srd_pd_output_callback_t cb, void *cb_data)
diff --git a/decoder.c b/decoder.c
index 3716537..c8eb98f 100644
--- a/decoder.c
+++ b/decoder.c
@@ -53,6 +53,8 @@ extern SRD_PRIV PyObject *mod_sigrokdecode;
  * This is a GSList containing the names of the decoders as strings.
  *
  * @return List of decoders, NULL if none are supported or loaded.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SRD_API const GSList *srd_decoder_list(void)
 {
@@ -65,6 +67,8 @@ SRD_API const GSList *srd_decoder_list(void)
  * @param id The ID string of the decoder to return.
  *
  * @return The decoder with the specified ID, or NULL if not found.
+ *
+ * @since 0.1.0
  */
 SRD_API struct srd_decoder *srd_decoder_get_by_id(const char *id)
 {
@@ -232,6 +236,8 @@ err_out:
  * @param module_name The module name to be loaded.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_decoder_load(const char *module_name)
 {
@@ -399,6 +405,8 @@ err_out:
  *
  * @return A newly allocated buffer containing the protocol decoder's
  *         documentation. The caller is responsible for free'ing the buffer.
+ *
+ * @since 0.1.0
  */
 SRD_API char *srd_decoder_doc_get(const struct srd_decoder *dec)
 {
@@ -445,6 +453,8 @@ static void free_probes(GSList *probelist)
  * @param dec The struct srd_decoder to be unloaded.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_decoder_unload(struct srd_decoder *dec)
 {
@@ -492,6 +502,8 @@ SRD_API int srd_decoder_unload(struct srd_decoder *dec)
  * Load all installed protocol decoders.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_decoder_load_all(void)
 {
@@ -517,6 +529,8 @@ SRD_API int srd_decoder_load_all(void)
  * Unload all loaded protocol decoders.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_decoder_unload_all(void)
 {
diff --git a/log.c b/log.c
index 7b30497..49a18eb 100644
--- a/log.c
+++ b/log.c
@@ -75,6 +75,8 @@ static char srd_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
  *                 SRD_LOG_WARN, SRD_LOG_INFO, SRD_LOG_DBG, or SRD_LOG_SPEW).
  *
  * @return SRD_OK upon success, SRD_ERR_ARG upon invalid loglevel.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_log_loglevel_set(int loglevel)
 {
@@ -94,6 +96,8 @@ SRD_API int srd_log_loglevel_set(int loglevel)
  * Get the libsigrokdecode loglevel.
  *
  * @return The currently configured libsigrokdecode loglevel.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_log_loglevel_get(void)
 {
@@ -113,6 +117,8 @@ SRD_API int srd_log_loglevel_get(void)
  *                  the caller does not need to keep it around.
  *
  * @return SRD_OK upon success, SRD_ERR_ARG upon invalid logdomain.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_log_logdomain_set(const char *logdomain)
 {
@@ -135,6 +141,8 @@ SRD_API int srd_log_logdomain_set(const char *logdomain)
  * @return A copy of the currently configured libsigrokdecode logdomain
  *         string. The caller is responsible for g_free()ing the string when
  *         it is no longer needed.
+ *
+ * @since 0.1.0
  */
 SRD_API char *srd_log_logdomain_get(void)
 {
@@ -154,6 +162,8 @@ SRD_API char *srd_log_logdomain_get(void)
  *                pass any data.
  *
  * @return SRD_OK upon success, SRD_ERR_ARG upon invalid arguments.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_log_callback_set(srd_log_callback_t cb, void *cb_data)
 {
@@ -176,6 +186,8 @@ SRD_API int srd_log_callback_set(srd_log_callback_t cb, void *cb_data)
  * Additionally, the internal 'srd_log_callback_data' pointer is set to NULL.
  *
  * @return SRD_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0
  */
 SRD_API int srd_log_callback_set_default(void)
 {
diff --git a/version.c b/version.c
index d509b5d..9449c2d 100644
--- a/version.c
+++ b/version.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of the libsigrokdecode project.
  *
- * Copyright (C) 2012 Uwe Hermann <uwe@hermann-uwe.de>
+ * Copyright (C) 2012-2013 Uwe Hermann <uwe@hermann-uwe.de>
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,52 +23,123 @@
 /**
  * @file
  *
- * Version number querying functions.
+ * Version number querying functions, definitions, and macros.
  */
 
 /**
  * @defgroup grp_versions Versions
  *
- * Version number querying functions.
+ * Version number querying functions, definitions, and macros.
+ *
+ * This set of API calls returns two different version numbers related
+ * to libsigrokdecode. The "package version" is the release version number
+ * of the libsigrokdecode tarball in the usual "major.minor.micro" format,
+ * e.g. "0.1.0".
+ *
+ * The "library version" is independent of that; it is the libtool version
+ * number in the "current:revision:age" format, e.g. "2:0:0".
+ * See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning for details.
+ *
+ * Both version numbers (and/or individual components of them) can be
+ * retrieved via the API calls at runtime, and/or they can be checked at
+ * compile/preprocessor time using the respective macros.
  *
  * @{
  */
 
+/**
+ * Get the major libsigrokdecode package version number.
+ *
+ * @return The major package version number.
+ *
+ * @since 0.1.0
+ */
 SRD_API int srd_package_version_major_get(void)
 {
 	return SRD_PACKAGE_VERSION_MAJOR;
 }
 
+/**
+ * Get the minor libsigrokdecode package version number.
+ *
+ * @return The minor package version number.
+ *
+ * @since 0.1.0
+ */
 SRD_API int srd_package_version_minor_get(void)
 {
 	return SRD_PACKAGE_VERSION_MINOR;
 }
 
+/**
+ * Get the micro libsigrokdecode package version number.
+ *
+ * @return The micro package version number.
+ *
+ * @since 0.1.0
+ */
 SRD_API int srd_package_version_micro_get(void)
 {
 	return SRD_PACKAGE_VERSION_MICRO;
 }
 
+/**
+ * Get the libsigrokdecode package version number as a string.
+ *
+ * @return The package version number string. The returned string is
+ *         static and thus should NOT be free'd by the caller.
+ *
+ * @since 0.1.0
+ */
 SRD_API const char *srd_package_version_string_get(void)
 {
 	return SRD_PACKAGE_VERSION_STRING;
 }
 
+/**
+ * Get the "current" part of the libsigrokdecode library version number.
+ *
+ * @return The "current" library version number.
+ *
+ * @since 0.1.0
+ */
 SRD_API int srd_lib_version_current_get(void)
 {
 	return SRD_LIB_VERSION_CURRENT;
 }
 
+/**
+ * Get the "revision" part of the libsigrokdecode library version number.
+ *
+ * @return The "revision" library version number.
+ *
+ * @since 0.1.0
+ */
 SRD_API int srd_lib_version_revision_get(void)
 {
 	return SRD_LIB_VERSION_REVISION;
 }
 
+/**
+ * Get the "age" part of the libsigrokdecode library version number.
+ *
+ * @return The "age" library version number.
+ *
+ * @since 0.1.0
+ */
 SRD_API int srd_lib_version_age_get(void)
 {
 	return SRD_LIB_VERSION_AGE;
 }
 
+/**
+ * Get the libsigrokdecode library version number as a string.
+ *
+ * @return The library version number string. The returned string is
+ *         static and thus should NOT be free'd by the caller.
+ *
+ * @since 0.1.0
+ */
 SRD_API const char *srd_lib_version_string_get(void)
 {
 	return SRD_LIB_VERSION_STRING;