Menu
▾
▴
[Hamlib-commits] Hamlib -- Ham radio control libraries branch master updated. 0f871a5a3e24a85414eb3a8bcfa9b6b9776406f0
|
From: n0nb <n0...@us...> - 2025-09-07 23:03:36
|
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Hamlib -- Ham radio control libraries".
The branch, master has been updated
via 0f871a5a3e24a85414eb3a8bcfa9b6b9776406f0 (commit)
from e762a812d08ab677808bd7f6d53adc87b3fa6195 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 0f871a5a3e24a85414eb3a8bcfa9b6b9776406f0
Author: Nate Bargmann <n0...@n0...>
Date: Sat Sep 6 18:13:12 2025 -0500
Update Doxygen comments for rigerror() and rigerror2()
Add a new topic of "Hamlib internals" with the group of lib_internal.
Address GitHub issue #1881.
diff --git a/doc/hamlib.cfg.in b/doc/hamlib.cfg.in
index 67817ca4b..8bdac4392 100644
--- a/doc/hamlib.cfg.in
+++ b/doc/hamlib.cfg.in
@@ -57,7 +57,7 @@ EXTRACT_STATIC = NO
HIDE_UNDOC_MEMBERS = NO
SHOW_INCLUDE_FILES = YES
INHERIT_DOCS = YES
-ENABLED_SECTIONS = ""
+ENABLED_SECTIONS = "hl_static"
PREDEFINED = DOXYGEN "DOC_HIDDEN"
JAVADOC_AUTOBRIEF = NO
OPTIMIZE_OUTPUT_FOR_C = YES
diff --git a/doc/index.doxygen b/doc/index.doxygen
index 5eada25a6..4a4b85edf 100644
--- a/doc/index.doxygen
+++ b/doc/index.doxygen
@@ -200,4 +200,5 @@ GNU/Linux.
* \defgroup amp_internal Amplifier Internal API
* \defgroup port Port data structure for accessing devices
* \defgroup utilities Utility Routines API
+ * \defgroup lib_internal Hamlib internals
*/
diff --git a/include/hamlib/rig.h b/include/hamlib/rig.h
index 0502e97ca..b78d4ca0c 100644
--- a/include/hamlib/rig.h
+++ b/include/hamlib/rig.h
@@ -200,43 +200,38 @@ extern HAMLIB_EXPORT_VAR(const char *) hamlib_copyright2;
/**
* \brief Hamlib error codes
+ *
* Error code definition that can be returned by the Hamlib functions.
- * Unless stated otherwise, Hamlib functions return the negative value
- * of rig_errcode_e definitions in case of error, or 0 when successful.
+ * Unless stated otherwise, in case of error Hamlib functions return the
+ * negative value of `rig_errcode_e` definitions, or `RIG_OK` when
+ * successful.
*/
- /**
- * @{ \name Hamlib error codes
- */
-
enum rig_errcode_e {
- RIG_OK = 0, /*!< 0 No error, operation completed successfully */
- RIG_EINVAL, /*!< 1 invalid parameter */
- RIG_ECONF, /*!< 2 invalid configuration (serial,..) */
- RIG_ENOMEM, /*!< 3 memory shortage */
- RIG_ENIMPL, /*!< 4 function not implemented, but will be */
- RIG_ETIMEOUT, /*!< 5 communication timed out */
- RIG_EIO, /*!< 6 IO error, including open failed */
- RIG_EINTERNAL, /*!< 7 Internal Hamlib error, huh! */
- RIG_EPROTO, /*!< 8 Protocol error */
- RIG_ERJCTED, /*!< 9 Command rejected by the rig */
- RIG_ETRUNC, /*!< 10 Command performed, but arg truncated */
- RIG_ENAVAIL, /*!< 11 Function not available */
- RIG_ENTARGET, /*!< 12 VFO not targetable */
- RIG_BUSERROR, /*!< 13 Error talking on the bus */
- RIG_BUSBUSY, /*!< 14 Collision on the bus */
- RIG_EARG, /*!< 15 NULL RIG handle or any invalid pointer parameter in get arg */
- RIG_EVFO, /*!< 16 Invalid VFO */
- RIG_EDOM, /*!< 17 Argument out of domain of func */
- RIG_EDEPRECATED,/*!< 18 Function deprecated */
- RIG_ESECURITY, /*!< 19 Security error */
- RIG_EPOWER, /*!< 20 Rig not powered on */
- RIG_ELIMIT, /*!< 21 Limit exceeded */
- RIG_EACCESS, /*!< 22 Access denied -- e.g. port already in use */
+ RIG_OK = 0, /*!< \c 0 No error, operation completed successfully */
+ RIG_EINVAL, /*!< \c 1 Invalid parameter */
+ RIG_ECONF, /*!< \c 2 Invalid configuration (serial,..) */
+ RIG_ENOMEM, /*!< \c 3 Memory shortage */
+ RIG_ENIMPL, /*!< \c 4 Function not implemented, but will be */
+ RIG_ETIMEOUT, /*!< \c 5 Communication timed out */
+ RIG_EIO, /*!< \c 6 IO error, including open failed */
+ RIG_EINTERNAL, /*!< \c 7 Internal Hamlib error, huh! */
+ RIG_EPROTO, /*!< \c 8 Protocol error */
+ RIG_ERJCTED, /*!< \c 9 Command rejected by the rig */
+ RIG_ETRUNC, /*!< \c 10 Command performed, but arg truncated */
+ RIG_ENAVAIL, /*!< \c 11 Function not available */
+ RIG_ENTARGET, /*!< \c 12 VFO not targetable */
+ RIG_BUSERROR, /*!< \c 13 Error talking on the bus */
+ RIG_BUSBUSY, /*!< \c 14 Collision on the bus */
+ RIG_EARG, /*!< \c 15 NULL RIG handle or any invalid pointer parameter in get arg */
+ RIG_EVFO, /*!< \c 16 Invalid VFO */
+ RIG_EDOM, /*!< \c 17 Argument out of domain of func */
+ RIG_EDEPRECATED,/*!< \c 18 Function deprecated */
+ RIG_ESECURITY, /*!< \c 19 Security error */
+ RIG_EPOWER, /*!< \c 20 Rig not powered on */
+ RIG_ELIMIT, /*!< \c 21 Limit exceeded */
+ RIG_EACCESS, /*!< \c 22 Access denied -- e.g. port already in use */
RIG_EEND // MUST BE LAST ITEM IN LAST
};
-/**
- * @}
- */
/**
* \brief Determines if the given error code indicates a "soft" error
diff --git a/src/rig.c b/src/rig.c
index 8e7c9c05a..288968ffd 100644
--- a/src/rig.c
+++ b/src/rig.c
@@ -22,11 +22,6 @@
*/
/* SPDX-License-Identifier: LGPL-2.1-or-later */
-/**
- * \addtogroup rig
- * @{
- */
-
/**
* \file src/rig.c
* \brief Ham Radio Control Libraries interface
@@ -50,6 +45,11 @@
* \example ../tests/testrig.c
*/
+/**
+ * \addtogroup rig
+ * @{
+ */
+
#include "hamlib/config.h"
#include "hamlib/rig.h"
#include "hamlib/rig_state.h"
@@ -75,21 +75,20 @@
/**
* \brief Hamlib short license name
- *
*/
const char *hamlib_license = "LGPL";
-/**
- * \brief Hamlib release number
- *
- * The version number has the format x.y.z
- */
+
/*
* Careful: The hamlib 1.2 ABI implicitly specifies a size of 21 bytes for
* the hamlib_version string. Changing the size provokes a warning from the
* dynamic loader.
+ *
+ * TODO: Remove and replace by hamlib_version2 for Hamlib 5.
*/
+
//! @cond Doxygen_Suppress
const char hamlib_version[21] = "Hamlib " PACKAGE_VERSION;
+
#if INTPTR_MAX == INT128_MAX
#define ARCHBITS "128-bit"
#elif INTPTR_MAX == INT64_MAX
@@ -98,8 +97,20 @@ const char hamlib_version[21] = "Hamlib " PACKAGE_VERSION;
#define ARCHBITS "32-bit"
#endif
//! @endcond
-const char *hamlib_version2 = "Hamlib " PACKAGE_VERSION " " HAMLIBDATETIME " "
- ARCHBITS;
+
+/**
+ * \brief Hamlib version string.
+ *
+ * The version number has the format x.y.z where:
+ * - *x* is a major version that indicates API/ABI changes from prior major versions
+ * - *y* is a minor version that indicates new device support
+ * - *z* is a point version that indicates bug fixes only
+ * - `PACKAGE_VERSION` is set in `configure.ac`.
+ * - `HAMLIBDATETIME` is generated at build time.
+ * - `ARCHBITS` is derived from tests of the build platform.
+ */
+const char *hamlib_version2 = "Hamlib " PACKAGE_VERSION " " HAMLIBDATETIME " " ARCHBITS;
+
HAMLIB_EXPORT_VAR(int) cookie_use;
HAMLIB_EXPORT_VAR(int) skip_init;
HAMLIB_EXPORT_VAR(int) lock_mode; // for use by rigctld
@@ -114,9 +125,10 @@ struct rig_caps caps_test;
const char *hamlib_copyright2 =
"Copyright (C) 2000-2012 Stephane Fillod\n"
"Copyright (C) 2000-2003 Frank Singleton\n"
- "Copyright (C) 2014-2020 Michael Black W9MDB\n"
+ "Copyright (C) 2014-2025 Michael Black W9MDB\n"
"This is free software; see the source for copying conditions. There is NO\n"
"warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.";
+
//! @cond Doxygen_Suppress
const char hamlib_copyright[231] = /* hamlib 1.2 ABI specifies 231 bytes */
"Copyright (C) 2000-2012 Stephane Fillod\n"
@@ -126,8 +138,7 @@ const char hamlib_copyright[231] = /* hamlib 1.2 ABI specifies 231 bytes */
//! @endcond
-#ifndef DOC_HIDDEN
-
+//! @cond Doxygen_Suppress
#if defined(WIN32) && !defined(__CYGWIN__)
# define DEFAULT_SERIAL_PORT "\\\\.\\COM1"
#elif BSD
@@ -214,11 +225,25 @@ struct opened_rig_l
struct opened_rig_l *next;
};
static struct opened_rig_l *opened_rig_list = { NULL };
+//! @endcond
-/*
- * Careful, the order must be the same as their RIG_E* counterpart!
- * TODO: localise the messages..
+/* My intention was to add this to the internal documentation, but Daxygen
+ * up through version 1.14 resolutely refuses to include it without doing
+ * project-wide settings like ENABLE_STATIC=yes and HIDE_UNDOC_MEMBERS=yes.
+ *
+ * Perhaps one day. Sigh...
+ */
+//! @cond hl_static
+/**
+ * @brief Plain text desrciptions of Hamlib error codes.
+ *
+ * @ingroup lib_internal
+ *
+ * @note Careful, the order must be the same as their RIG_E* counterpart in
+ * rig_errcode_e and this structure must be kept in sync with rig_errcode_e!
+ *
+ * @todo Localise the messages.
*/
static const char *const rigerror_table[] =
{
@@ -246,10 +271,19 @@ static const char *const rigerror_table[] =
"Limit exceeded",
"Access denied"
};
+//! @endcond
-
+/**
+ * @brief Convenience macro calculating `rigerror_table` size.
+ *
+ * @ingroup lib_internal
+ *
+ * Used to ensure access beyond the end of `rigerror_table` does
+ * not occur.
+ * */
#define ERROR_TBL_SZ (sizeof(rigerror_table)/sizeof(char *))
+//! @cond Doxygen_Suppress
typedef struct async_data_handler_args_s
{
RIG *rig;
@@ -334,6 +368,7 @@ static int remove_opened_rig(const RIG *rig)
return (-RIG_EINVAL); /* Not found in list ! */
}
+//! @endcond
/**
@@ -370,8 +405,6 @@ int foreach_opened_rig(int (*cfunc)(RIG *, rig_ptr_t), rig_ptr_t data)
return (RIG_OK);
}
-#endif /* !DOC_HIDDEN */
-
char debugmsgsave[DEBUGMSGSAVE_SIZE] = "";
char debugmsgsave2[DEBUGMSGSAVE_SIZE] = ""; // deprecated
@@ -379,6 +412,17 @@ char debugmsgsave3[DEBUGMSGSAVE_SIZE] = ""; // deprecated
MUTEX(mutex_debugmsgsave);
+
+/**
+ * @brief Handle stack trace messages.
+ *
+ * @ingroup lib_internal
+ *
+ * Maintains an array of debug messages to build a stack trace of up to 20
+ * lines.
+ *
+ * @sa rigerror()
+ */
void add2debugmsgsave(const char *s)
{
const char *p;
@@ -431,16 +475,19 @@ void add2debugmsgsave(const char *s)
MUTEX_UNLOCK(mutex_debugmsgsave);
}
+
/**
- * \brief get string describing the error code
- * \param errnum The error code
- * \return the appropriate description string, otherwise a NULL pointer
- * if the error code is unknown.
+ * \brief Get the string describing the passed error code.
+ *
+ * Simple version of rigerror() as it only outputs a short predefined string.
+ *
+ * \param errnum The error code defined in #rig_errcode_e, e.g. RIG_OK.
*
- * Returns a string describing the error code passed in the argument \a
- * errnum.
+ * \return The matched description string from `rigerror_table`, otherwise
+ * `"ERR_OUT_OF_RANGE"` if `errnum` exceeds the number of strings defined in
+ * `rigerror_table`.
*
- * \todo support gettext/localization
+ * \todo Support gettext/localization
*/
const char *HAMLIB_API rigerror2(int errnum) // returns single-line message
{
@@ -457,6 +504,19 @@ const char *HAMLIB_API rigerror2(int errnum) // returns single-line message
return msg;
}
+
+/**
+ * @brief Add error message to debug output.
+ *
+ * \param errnum The error code defined in #rig_errcode_e, e.g. RIG_OK.
+ *
+ * @return Pointer to the complete debug output otherwise `"ERR_OUT_OF_RANGE"`
+ * if `errnum` exceeds the number of strings defined in `rigerror_table`.
+ *
+ * @sa add2debugmsgsave()
+ *
+ * \todo Support gettext/localization
+ */
const char *HAMLIB_API rigerror(int errnum)
{
errnum = abs(errnum);
-----------------------------------------------------------------------
Summary of changes:
doc/hamlib.cfg.in | 2 +-
doc/index.doxygen | 1 +
include/hamlib/rig.h | 59 ++++++++++++--------------
src/rig.c | 118 ++++++++++++++++++++++++++++++++++++++-------------
4 files changed, 118 insertions(+), 62 deletions(-)
hooks/post-receive
--
Hamlib -- Ham radio control libraries
|
