Commit 9fb5f2df authored by Uwe Hermann's avatar Uwe Hermann

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.
parent 22f8cb54
...@@ -143,6 +143,22 @@ Doxygen ...@@ -143,6 +143,22 @@ Doxygen
/** @endcond */, so that Doxygen doesn't include them in the output. /** @endcond */, so that Doxygen doesn't include them in the output.
Variables that are "static" don't need to be marked like this. 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 Testsuite
--------- ---------
......
...@@ -319,6 +319,8 @@ static int sanity_check_all_output_modules(void) ...@@ -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 '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 * the context will be free'd by sr_exit() as part of the libsigrok
* shutdown. * shutdown.
*
* @since 0.1.0 (but the API changed in 0.2.0)
*/ */
SR_API int sr_init(struct sr_context **ctx) SR_API int sr_init(struct sr_context **ctx)
{ {
...@@ -378,6 +380,8 @@ done: ...@@ -378,6 +380,8 @@ done:
* @param ctx Pointer to a libsigrok context struct. Must not be NULL. * @param ctx Pointer to a libsigrok context struct. Must not be NULL.
* *
* @return SR_OK upon success, a (negative) error code otherwise. * @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) SR_API int sr_exit(struct sr_context *ctx)
{ {
......
...@@ -79,6 +79,8 @@ SR_PRIV struct sr_probe *sr_probe_new(int index, int type, ...@@ -79,6 +79,8 @@ SR_PRIV struct sr_probe *sr_probe_new(int index, int type,
* of the string is made. * of the string is made.
* *
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments. * @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, SR_API int sr_dev_probe_name_set(const struct sr_dev_inst *sdi,
int probenum, const char *name) int probenum, const char *name)
...@@ -114,6 +116,8 @@ SR_API int sr_dev_probe_name_set(const struct sr_dev_inst *sdi, ...@@ -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. * @param state TRUE to enable the probe, FALSE to disable.
* *
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments. * @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, SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum,
gboolean state) gboolean state)
...@@ -149,6 +153,8 @@ SR_API int sr_dev_probe_enable(const struct sr_dev_inst *sdi, int probenum, ...@@ -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 * @param trigger Trigger string, in the format used by sigrok-cli
* *
* @return SR_OK on success, or SR_ERR_ARG on invalid arguments. * @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, SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum,
const char *trigger) const char *trigger)
...@@ -189,6 +195,8 @@ SR_API int sr_dev_trigger_set(const struct sr_dev_inst *sdi, int probenum, ...@@ -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. * @return TRUE if the device has the specified option, FALSE otherwise.
* FALSE is also returned on invalid input parameters or other * FALSE is also returned on invalid input parameters or other
* error conditions. * 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) 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) ...@@ -257,7 +265,6 @@ SR_PRIV void sr_dev_inst_free(struct sr_dev_inst *sdi)
g_free(sdi->model); g_free(sdi->model);
g_free(sdi->version); g_free(sdi->version);
g_free(sdi); g_free(sdi);
} }
#ifdef HAVE_LIBUSB_1_0 #ifdef HAVE_LIBUSB_1_0
...@@ -290,17 +297,21 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb) ...@@ -290,17 +297,21 @@ SR_PRIV void sr_usb_dev_inst_free(struct sr_usb_dev_inst *usb)
#endif #endif
/** @private /**
* @param pathname OS-specific serial port specification. Examples: * @private
* "/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.
* *
* Both parameters are copied to newly allocated strings, and freed * Both parameters are copied to newly allocated strings, and freed
* automatically by sr_serial_dev_inst_free(). * 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, SR_PRIV struct sr_serial_dev_inst *sr_serial_dev_inst_new(const char *port,
const char *serialcomm) const char *serialcomm)
......
...@@ -41,10 +41,14 @@ ...@@ -41,10 +41,14 @@
* Return a human-readable error string for the given libsigrok error code. * 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. * @param error_code A libsigrok error code number, such as SR_ERR_MALLOC.
*
* @return A const string containing a short, human-readable (English) * @return A const string containing a short, human-readable (English)
* description of the error, such as "memory allocation error". * description of the error, such as "memory allocation error".
* The string must NOT be free'd by the caller! * The string must NOT be free'd by the caller!
*
* @see sr_strerror_name * @see sr_strerror_name
*
* @since 0.2.0
*/ */
SR_API const char *sr_strerror(int error_code) SR_API const char *sr_strerror(int error_code)
{ {
...@@ -89,9 +93,13 @@ 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. * a libsigrok error code is useful.
* *
* @param error_code A libsigrok error code number, such as SR_ERR_MALLOC. * @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. * @return A const string containing the "name" of the error code as string.
* The string must NOT be free'd by the caller! * The string must NOT be free'd by the caller!
*
* @see sr_strerror * @see sr_strerror
*
* @since 0.2.0
*/ */
SR_API const char *sr_strerror_name(int error_code) SR_API const char *sr_strerror_name(int error_code)
{ {
......
...@@ -95,6 +95,8 @@ ...@@ -95,6 +95,8 @@
* or SR_ERR_ARG upon invalid arguments. * or SR_ERR_ARG upon invalid arguments.
* If something other than SR_OK is returned, the values of * If something other than SR_OK is returned, the values of
* out_unitsize, data_out, and length_out are undefined. * 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, SR_API int sr_filter_probes(unsigned int in_unitsize, unsigned int out_unitsize,
const GArray *probe_array, const uint8_t *data_in, const GArray *probe_array, const uint8_t *data_in,
......
...@@ -74,6 +74,8 @@ static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT; ...@@ -74,6 +74,8 @@ static char sr_log_domain[LOGDOMAIN_MAXLEN + 1] = LOGDOMAIN_DEFAULT;
* SR_LOG_INFO, SR_LOG_DBG, or SR_LOG_SPEW). * SR_LOG_INFO, SR_LOG_DBG, or SR_LOG_SPEW).
* *
* @return SR_OK upon success, SR_ERR_ARG upon invalid loglevel. * @return SR_OK upon success, SR_ERR_ARG upon invalid loglevel.
*
* @since 0.1.0
*/ */
SR_API int sr_log_loglevel_set(int loglevel) SR_API int sr_log_loglevel_set(int loglevel)
{ {
...@@ -93,6 +95,8 @@ 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. * Get the libsigrok loglevel.
* *
* @return The currently configured libsigrok loglevel. * @return The currently configured libsigrok loglevel.
*
* @since 0.1.0
*/ */
SR_API int sr_log_loglevel_get(void) SR_API int sr_log_loglevel_get(void)
{ {
...@@ -112,6 +116,8 @@ 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. * the caller does not need to keep it around.
* *
* @return SR_OK upon success, SR_ERR_ARG upon invalid logdomain. * @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) SR_API int sr_log_logdomain_set(const char *logdomain)
{ {
...@@ -134,6 +140,8 @@ 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 * @return A copy of the currently configured libsigrok logdomain
* string. The caller is responsible for g_free()ing the string when * string. The caller is responsible for g_free()ing the string when
* it is no longer needed. * it is no longer needed.
*
* @since 0.1.0
*/ */
SR_API char *sr_log_logdomain_get(void) SR_API char *sr_log_logdomain_get(void)
{ {
...@@ -152,6 +160,8 @@ 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. * 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. * @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) 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) ...@@ -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. * Additionally, the internal 'sr_log_callback_data' pointer is set to NULL.
* *
* @return SR_OK upon success, a negative error code otherwise. * @return SR_OK upon success, a negative error code otherwise.
*
* @since 0.1.0
*/ */
SR_API int sr_log_callback_set_default(void) SR_API int sr_log_callback_set_default(void)
{ {
......
...@@ -31,44 +31,114 @@ ...@@ -31,44 +31,114 @@
* *
* Version number querying functions, definitions, and macros. * 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) SR_API int sr_package_version_major_get(void)
{ {
return SR_PACKAGE_VERSION_MAJOR; 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) SR_API int sr_package_version_minor_get(void)
{ {
return SR_PACKAGE_VERSION_MINOR; 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) SR_API int sr_package_version_micro_get(void)
{ {
return SR_PACKAGE_VERSION_MICRO; 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) SR_API const char *sr_package_version_string_get(void)
{ {
return SR_PACKAGE_VERSION_STRING; 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) SR_API int sr_lib_version_current_get(void)
{ {
return SR_LIB_VERSION_CURRENT; 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) SR_API int sr_lib_version_revision_get(void)
{ {
return SR_LIB_VERSION_REVISION; 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) SR_API int sr_lib_version_age_get(void)
{ {
return SR_LIB_VERSION_AGE; 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) SR_API const char *sr_lib_version_string_get(void)
{ {
return SR_LIB_VERSION_STRING; return SR_LIB_VERSION_STRING;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment