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.
This commit is contained in:
Uwe Hermann
parent
22f8cb54d1
commit
9fb5f2dfa6
16
HACKING
16
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
|
||||
---------
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
{
|
||||
|
|
|
|||
29
device.c
29
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)
|
||||
|
|
|
|||
8
error.c
8
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)
|
||||
{
|
||||
|
|
|
|||
2
filter.c
2
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,
|
||||
|
|
|
|||
12
log.c
12
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)
|
||||
{
|
||||
|
|
|
|||
70
version.c
70
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;
|
||||
|
|
|
|||
Loading…
Reference in New Issue