From: Uwe Hermann <redacted>
Date: Sat, 13 Apr 2013 16:58:11 +0000 (+0200)
Subject: Doxygen: Add @since markers.
X-Git-Tag: dsupstream~131
X-Git-Url: https://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=9fb5f2dfa6bcded8082677ed3b915ff6b880cfab;hp=22f8cb54d18bf4abd5a7513a509539f15570784c

Doxygen: Add @since markers.

Add @since tags to some (not all yet) public API functions, to document
in which release they were added (and/or in which release there were
API changes).

Document the @since usage in HACKING.

Also, add Doxygen docs for the functions in version.c.
---

diff --git a/HACKING b/HACKING
index faac0a8c..cf407c98 100644
--- a/HACKING
+++ b/HACKING
@@ -143,6 +143,22 @@ Doxygen
    /** @endcond */, so that Doxygen doesn't include them in the output.
    Variables that are "static" don't need to be marked like this.
 
+ - Mark all public API functions (SR_API) with a @since tag which indicates
+   in which release the respective function was added. If the function has
+   existed before, but its API changed later, document this as well.
+
+   Non-public functions (static ones, and those marked SR_PRIV) don't need
+   to have @since markers.
+
+   The @since tag should be the last one, i.e. it should come after @param,
+   @return, @see, and so on.
+
+   Examples:
+
+     @since 0.1.0
+
+     @since 0.1.1 (but the API changed in 0.2.0)
+
 
 Testsuite
 ---------
diff --git a/backend.c b/backend.c
index eeaea245..cd1d1db2 100644
--- a/backend.c
+++ b/backend.c
@@ -319,6 +319,8 @@ static int sanity_check_all_output_modules(void)
  *         the 'ctx' pointer is undefined and should not be used. Upon success,
  *         the context will be free'd by sr_exit() as part of the libsigrok
  *         shutdown.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SR_API int sr_init(struct sr_context **ctx)
 {
@@ -378,6 +380,8 @@ done:
  * @param ctx Pointer to a libsigrok context struct. Must not be NULL.
  *
  * @return SR_OK upon success, a (negative) error code otherwise.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SR_API int sr_exit(struct sr_context *ctx)
 {
diff --git a/device.c b/device.c
index 0a78a802..62395be5 100644
--- a/device.c
+++ b/device.c
@@ -79,6 +79,8 @@ SR_PRIV struct sr_probe *sr_probe_new(int index, int type,
  *             of the string is made.
  *
  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SR_API int sr_dev_probe_name_set(const struct sr_dev_inst *sdi,
 		int probenum, const char *name)
@@ -114,6 +116,8 @@ SR_API int sr_dev_probe_name_set(const struct sr_dev_inst *sdi,
  * @param state TRUE to enable the probe, FALSE to disable.
  *
  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
+ *
+ * @since 0.2.0
  */
 SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum,
 		gboolean state)
@@ -149,6 +153,8 @@ SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum,
  * @param trigger Trigger string, in the format used by sigrok-cli
  *
  * @return SR_OK on success, or SR_ERR_ARG on invalid arguments.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum,
 		const char *trigger)
@@ -189,6 +195,8 @@ SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum,
  * @return TRUE if the device has the specified option, FALSE otherwise.
  *         FALSE is also returned on invalid input parameters or other
  *         error conditions.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SR_API gboolean sr_dev_has_option(const struct sr_dev_inst *sdi, int key)
 {
@@ -257,7 +265,6 @@ SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
 	g_free(sdi->model);
 	g_free(sdi->version);
 	g_free(sdi);
-
 }
 
 #ifdef HAVE_LIBUSB_1_0
@@ -290,17 +297,21 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
 
 #endif
 
-/** @private
- * @param pathname OS-specific serial port specification. Examples:
- * "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
- * @param serialcomm A serial communication parameters string, in the form
- * of <speed>/<data bits><parity><stopbits>, for example "9600/8n1" or
- * "600/7o2". This is an optional parameter; it may be filled in later.
- * @return A pointer to a newly initialized struct sr_serial_dev_inst,
- * or NULL on error.
+/**
+ * @private
  *
  * Both parameters are copied to newly allocated strings, and freed
  * automatically by sr_serial_dev_inst_free().
+ *
+ * @param pathname OS-specific serial port specification. Examples:
+ *                 "/dev/ttyUSB0", "/dev/ttyACM1", "/dev/tty.Modem-0", "COM1".
+ * @param serialcomm A serial communication parameters string, in the form
+ *                   of <speed>/<data bits><parity><stopbits>, for example
+ *                   "9600/8n1" or "600/7o2". This is an optional parameter;
+ *                   it may be filled in later.
+ *
+ * @return A pointer to a newly initialized struct sr_serial_dev_inst,
+ *         or NULL on error.
  */
 SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
 		const char *serialcomm)
diff --git a/error.c b/error.c
index c9b8589e..01fb7912 100644
--- a/error.c
+++ b/error.c
@@ -41,10 +41,14 @@
  * Return a human-readable error string for the given libsigrok error code.
  *
  * @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
+ *
  * @return A const string containing a short, human-readable (English)
  *         description of the error, such as "memory allocation error".
  *         The string must NOT be free'd by the caller!
+ *
  * @see sr_strerror_name
+ *
+ * @since 0.2.0
  */
 SR_API const char *sr_strerror(int error_code)
 {
@@ -89,9 +93,13 @@ SR_API const char *sr_strerror(int error_code)
  * a libsigrok error code is useful.
  *
  * @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
+ *
  * @return A const string containing the "name" of the error code as string.
  *         The string must NOT be free'd by the caller!
+ *
  * @see sr_strerror
+ *
+ * @since 0.2.0
  */
 SR_API const char *sr_strerror_name(int error_code)
 {
diff --git a/filter.c b/filter.c
index 80c0d67a..3526f91f 100644
--- a/filter.c
+++ b/filter.c
@@ -95,6 +95,8 @@
  *         or SR_ERR_ARG upon invalid arguments.
  *         If something other than SR_OK is returned, the values of
  *         out_unitsize, data_out, and length_out are undefined.
+ *
+ * @since 0.1.0 (but the API changed in 0.2.0)
  */
 SR_API int sr_filter_probes(unsigned int in_unitsize, unsigned int out_unitsize,
 			    const GArray *probe_array, const uint8_t *data_in,
diff --git a/log.c b/log.c
index 6ebede70..228f3cc4 100644
--- a/log.c
+++ b/log.c
@@ -74,6 +74,8 @@ static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
  *                 SR_LOG_INFO, SR_LOG_DBG, or SR_LOG_SPEW).
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid loglevel.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_loglevel_set(int loglevel)
 {
@@ -93,6 +95,8 @@ SR_API int sr_log_loglevel_set(int loglevel)
  * Get the libsigrok loglevel.
  *
  * @return The currently configured libsigrok loglevel.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_loglevel_get(void)
 {
@@ -112,6 +116,8 @@ SR_API int sr_log_loglevel_get(void)
  *                  the caller does not need to keep it around.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid logdomain.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_logdomain_set(const char *logdomain)
 {
@@ -134,6 +140,8 @@ SR_API int sr_log_logdomain_set(const char *logdomain)
  * @return A copy of the currently configured libsigrok logdomain
  *         string. The caller is responsible for g_free()ing the string when
  *         it is no longer needed.
+ *
+ * @since 0.1.0
  */
 SR_API char *sr_log_logdomain_get(void)
 {
@@ -152,6 +160,8 @@ SR_API char *sr_log_logdomain_get(void)
  *                to be NULL if the caller doesn't need/want to pass any data.
  *
  * @return SR_OK upon success, SR_ERR_ARG upon invalid arguments.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_callback_set(sr_log_callback_t cb, void *cb_data)
 {
@@ -174,6 +184,8 @@ SR_API int sr_log_callback_set(sr_log_callback_t cb, void *cb_data)
  * Additionally, the internal 'sr_log_callback_data' pointer is set to NULL.
  *
  * @return SR_OK upon success, a negative error code otherwise.
+ *
+ * @since 0.1.0
  */
 SR_API int sr_log_callback_set_default(void)
 {
diff --git a/version.c b/version.c
index 51f344bd..c9889f82 100644
--- a/version.c
+++ b/version.c
@@ -31,44 +31,114 @@
  *
  * Version number querying functions, definitions, and macros.
  *
+ * This set of API calls returns two different version numbers related
+ * to libsigrok. The "package version" is the release version number of the
+ * libsigrok 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 libsigrok package version number.
+ *
+ * @return The major package version number.
+ *
+ * @since 0.1.0
+ */
 SR_API int sr_package_version_major_get(void)
 {
 	return SR_PACKAGE_VERSION_MAJOR;
 }
 
+/**
+ * Get the minor libsigrok package version number.
+ *
+ * @return The minor package version number.
+ *
+ * @since 0.1.0
+ */
 SR_API int sr_package_version_minor_get(void)
 {
 	return SR_PACKAGE_VERSION_MINOR;
 }
 
+/**
+ * Get the micro libsigrok package version number.
+ *
+ * @return The micro package version number.
+ *
+ * @since 0.1.0
+ */
 SR_API int sr_package_version_micro_get(void)
 {
 	return SR_PACKAGE_VERSION_MICRO;
 }
 
+/**
+ * Get the libsigrok 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
+ */
 SR_API const char *sr_package_version_string_get(void)
 {
 	return SR_PACKAGE_VERSION_STRING;
 }
 
+/**
+ * Get the "current" part of the libsigrok library version number.
+ *
+ * @return The "current" library version number.
+ *
+ * @since 0.1.0
+ */
 SR_API int sr_lib_version_current_get(void)
 {
 	return SR_LIB_VERSION_CURRENT;
 }
 
+/**
+ * Get the "revision" part of the libsigrok library version number.
+ *
+ * @return The "revision" library version number.
+ *
+ * @since 0.1.0
+ */
 SR_API int sr_lib_version_revision_get(void)
 {
 	return SR_LIB_VERSION_REVISION;
 }
 
+/**
+ * Get the "age" part of the libsigrok library version number.
+ *
+ * @return The "age" library version number.
+ *
+ * @since 0.1.0
+ */
 SR_API int sr_lib_version_age_get(void)
 {
 	return SR_LIB_VERSION_AGE;
 }
 
+/**
+ * Get the libsigrok 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
+ */
 SR_API const char *sr_lib_version_string_get(void)
 {
 	return SR_LIB_VERSION_STRING;