Merge pull request #1268 from dforsi/fix/doxygen

Add/fix Doxygen comments
2023-04-09 22:13:42 -05:00 · 2023-04-09 22:13:42 -05:00 · cf77666cc1
commit cf77666cc1
--- a/2
+++ b/2
@ -21,7 +21,7 @@ Version 4.6
        * Add rigctlsync utility to synchronize frequency from a rig to SDR# (or others)
        * Add SDR# rig for use with SDR#'s gpredict plugin -- can only get/set freq 
        * Add Apex Shared Loop rotator -- unidirectional only so far
-        * Add client_version to rigctld so client can report it's version for future use/compatility/alternatives
+        * Add client_version to rigctld so client can report it's version for future use/compatibility/alternatives
        * Add --set-conf=tuner_control_pathname=hamlib_tuner_control (default)
          If file exists then it will be called with 0/1 (Off/On) argument
          with 'U TUNER 0' or 'U TUNER 1"
--- a/doc/README.man-pages
+++ b/doc/README.man-pages
@ -159,7 +159,7 @@ PDF as blocks of constant width text and should be verbatim input or output
 in the shell, programs, or blocks of source code.

 Text intended to be typed at a shell or program prompt should be in bold and
-program orshell output in normal weight.  In some cases it will be necessary
+program or shell output in normal weight.  In some cases it will be necessary
 to use the "\fB...\fP" font formatting calls especially where backslash
 escapes ("\\") are required.

--- a/doc/hamlib.cfg.in
+++ b/doc/hamlib.cfg.in
@ -17,7 +17,7 @@ MAN_EXTENSION	= .3
 # Set GENERATE_LATEX to YES to generate the needed files for the PDF manual
 # and run 'make doc'.  Then 'cd latex ; make' to generate the PDF manual.
 #
-# See section 1.3.1.2 in @top_srcdir@/README.developer for the needed LaTEX
+# See section 1.3.1.2 in @top_srcdir@/README.developer for the needed LaTeX
 # packages.
 USE_PDFLATEX    = YES
 PDF_HYPERLINKS  = YES
--- a/extra/kylix/README.kylix
+++ b/extra/kylix/README.kylix
@ -16,13 +16,13 @@ hamlib_rotapi.pas
 HamlibComponents.pas

    This file contain two components that encapsulate the rig and rotator 
-    frontends.  It is very simular to the C++ class.
+    frontends.  It is very similar to the C++ class.

  
 A simple test program is included in the tests/ directory.  It implements
 a selection dialog and a very simple Radio Control dialog.

-This binding was develop with Borland Kylix Open Edition Ver 2.0. Open Edition
+This binding was developed with Borland Kylix Open Edition Ver 2.0. Open Edition
 is freely downloadable from Borland's website for use with GPL projects.
 http://www.borland.com/kylix/

--- a/extra/kylix/hamlib_rigapi.pas
+++ b/extra/kylix/hamlib_rigapi.pas
@ -327,7 +327,7 @@ const
 //#define RIG_IS_TOKEN_FRONTEND(t) ((t)&(1<<30))

    {*
-     * strongly inspired from soundmedem. Thanks Thomas!
+     * strongly inspired from soundmodem. Thanks Thomas!
     *}
    RIG_CONF_STRING = 0;
    RIG_CONF_COMBO = 1;
@ -472,7 +472,7 @@ type

 const
    {*
-     * tranceive mode, ie. the rig notify the host of any event,
+     * transceive mode, ie. the rig notify the host of any event,
     * like freq changed, mode changed, etc.
     *}
    RIG_TRN_OFF  = 0;
--- a/include/hamlib/rig.h
+++ b/include/hamlib/rig.h
@ -537,7 +537,7 @@ typedef unsigned int vfo_t;
 /** \brief \c Macro to tell you if VFO can transmit */
 #define RIG_VFO_TX_VFO(v)   ((v)|RIG_VFO_TX_FLAG)

-/** \brief \c TX -- alias for split tx or uplink, of VFO_CURR  */
+/** \brief \c TX -- alias for split tx or uplink, of VFO_CURR */
 #define RIG_VFO_TX          RIG_VFO_TX_VFO(RIG_VFO_CURR)

 /** \brief \c RX -- alias for split rx or downlink */
@ -565,7 +565,7 @@ typedef unsigned int vfo_t;
 #define RIG_TARGETABLE_ANT (1<<10)
 #define RIG_TARGETABLE_ROOFING (1<<11) // roofing filter targetable by VFO
 #define RIG_TARGETABLE_SPECTRUM (1<<12) // spectrum scope targetable by VFO
-#define RIG_TARGETABLE_BAND (1<<13) // Band select -- e.g. Yaeus BS command
+#define RIG_TARGETABLE_BAND (1<<13) // Band select -- e.g. Yaesu BS command
 #define RIG_TARGETABLE_COMMON (RIG_TARGETABLE_RITXIT | RIG_TARGETABLE_PTT | RIG_TARGETABLE_MEM | RIG_TARGETABLE_BANK)
 #define RIG_TARGETABLE_ALL  0x7fffffff
 //! @endcond
@ -779,7 +779,7 @@ typedef long token_t;
 *
 *   Current internal implementation
 *   NUMERIC: val.f or val.i
- *   COMBO: val.i, starting from 0.  Points to a table of strings or asci stored values.
+ *   COMBO: val.i, starting from 0.  Points to a table of strings or ASCII stored values.
 *   STRING: val.s or val.cs
 *   CHECKBUTTON: val.i 0/1
 *   BINARY: val.b
@ -2586,7 +2586,7 @@ struct rig_state {
    int lock_mode; /*!< flag that prevents mode changes if ~= 0 -- see set/get_lock_mode */
    powerstat_t powerstat; /*!< power status */
    char *tuner_control_pathname;  /*!< Path to external tuner control program that get 0/1 (Off/On) argument */
-    char client_version[32];  /*!<! Allow client to report version for compatility checks/capability */
+    char client_version[32];  /*!<! Allow client to report version for compatibility checks/capability */
    freq_t offset_vfoa; /*!< Offset to apply to VFOA/Main set_freq */
    freq_t offset_vfob; /*!< Offset to apply to VFOB/Sub set_freq */
 };
--- a/include/hamlib/riglist.h
+++ b/include/hamlib/riglist.h
@ -33,6 +33,8 @@
 #define RIG_MAKE_MODEL(a,b) ((a)*MAX_MODELS_PER_BACKEND+(b))
 #define RIG_BACKEND_NUM(a) ((a)/MAX_MODELS_PER_BACKEND)

+//! @endcond
+
 /*! \file riglist.h
 *  \brief Hamlib rig(radio) model definitions.
 *
@ -49,6 +51,13 @@
 *  whishes to use. It is done with the rig_init() API call.
 */

+/**
+ * \def RIG_MODEL_NONE
+ * \brief A macro that returns the model number for an unknown model.
+ *
+ * The none backend, as the name suggests, does nothing.  It is mainly for
+ * internal use.
+ */
 #define RIG_MODEL_NONE 0

 /*! \def RIG_MODEL_DUMMY
@ -62,9 +71,12 @@
 *  It has also been expanded to provide support to "virtual" type of rigs
 *  such as the network rig control backend and W1HKJ's Flrig application.
 */
+//! @cond Doxygen_Suppress
 #define RIG_DUMMY 0
 #define RIG_BACKEND_DUMMY "dummy"
+//! @endcond
 #define RIG_MODEL_DUMMY RIG_MAKE_MODEL(RIG_DUMMY, 1)
+//! @cond Doxygen_Suppress
 #define RIG_MODEL_NETRIGCTL RIG_MAKE_MODEL(RIG_DUMMY, 2)
 #define RIG_MODEL_ARMSTRONG RIG_MAKE_MODEL(RIG_DUMMY, 3)
 #define RIG_MODEL_FLRIG RIG_MAKE_MODEL(RIG_DUMMY, 4)
@ -629,7 +641,6 @@
 #define RIG_GOMSPACE 35
 #define RIG_BACKEND_GOMSPACE "gomspace"
 #define RIG_MODEL_GS100 RIG_MAKE_MODEL(RIG_GOMSPACE, 1)
-//! @endcond

 /*
 * MDS Microwave Data Systems https://en.wikipedia.org/wiki/Microwave_Data_Systems
@ -645,6 +656,7 @@
    etc.
 */

+//! @endcond

 /*! \typedef typedef int rig_model_t
    \brief Convenience type definition for rig model.
--- a/rigs/jrc/jst145.c
+++ b/rigs/jrc/jst145.c
@ -506,7 +506,7 @@ static int jst145_get_mode(RIG *rig, vfo_t vfo, rmode_t *mode, pbwidth_t *width)

    if (retval != RIG_OK)
    {
-        rig_debug(RIG_DEBUG_ERR, "%s: jrc_transcation failed: %s\n", __func__,
+        rig_debug(RIG_DEBUG_ERR, "%s: jrc_transaction failed: %s\n", __func__,
                  rigerror(retval));
    }

--- a/rigs/uniden/uniden_digital.c
+++ b/rigs/uniden/uniden_digital.c
@ -46,7 +46,7 @@
 * use the address returned from one of the commands.  If you decide
 * the latter method, the order is slightly confusing but, I have it
 * well documented within DSctl.  The latter method is also as much
- * as 30% faster then using the Uniden software or "Get Next
+ * as 30% faster than using the Uniden software or "Get Next
 * Location" command.
 */

--- a/rigs/yaesu/newcat.c
+++ b/rigs/yaesu/newcat.c
@ -3536,7 +3536,7 @@ int newcat_set_powerstat(RIG *rig, powerstat_t status)

    ENTERFUNC;

-#if 0 // all Yaeus rigs have PS and calling this here interferes with power on
+#if 0 // all Yaesu rigs have PS and calling this here interferes with power on

    if (!newcat_valid_command(rig, "PS"))
    {
@ -7809,7 +7809,7 @@ int newcat_set_tx_vfo(RIG *rig, vfo_t tx_vfo)

    if (is_ftdx101d || is_ftdx101mp)
    {
-        // what other Yaeus rigs should be using this?
+        // what other Yaesu rigs should be using this?
        // The DX101D returns FT0 when in split and not transmitting
        command = "ST";
    }
@ -7840,7 +7840,7 @@ int newcat_get_tx_vfo(RIG *rig, vfo_t *tx_vfo)

    if (is_ftdx101d || is_ftdx101mp)
    {
-        // what other Yaeus rigs should be using this?
+        // what other Yaesu rigs should be using this?
        // The DX101D returns FT0 when in split and not transmitting
        command = "ST";
    }
@ -10897,7 +10897,7 @@ int newcat_set_cmd_validate(RIG *rig)
        {
            // for the BS command we can only run it once
            // so we'll assume it worked
-            // maybe Yaeus will make this command more intelligent
+            // maybe Yaesu will make this command more intelligent
            if (strstr(priv->cmd_str, "BS")) { RETURNFUNC(RIG_OK); }

            // if the first two chars match we are validated
--- a/src/amplifier.c
+++ b/src/amplifier.c
@ -132,7 +132,7 @@ static int remove_opened_amp(const AMP *amp)

 #ifdef XXREMOVEDXX
 /**
- * \brief Executess cfunc() on each #AMP handle.
+ * \brief Executes cfunc() on each #AMP handle.
 *
 * \param cfunc The function to be executed on each #AMP handle.
 * \param data Data pointer to be passed to cfunc()
--- a/src/cache.c
+++ b/src/cache.c
@ -26,6 +26,7 @@
 #define CHECK_RIG_ARG(r) (!(r) || !(r)->caps || !(r)->state.comm_state)

 /**
+ * \file cache.c
 * \addtogroup rig
 * @{
 */
--- a/src/rig.c
+++ b/src/rig.c
@ -843,7 +843,7 @@ int HAMLIB_API rig_open(RIG *rig)
        RETURNFUNC(-RIG_EINVAL);
    }

-    // rigctl/rigctld may have deprecated values -- backwards compatility
+    // rigctl/rigctld may have deprecated values -- backwards compatibility
    if (rs->rigport_deprecated.pathname[0] != 0)
    {
        strcpy(rs->rigport.pathname, rs->rigport_deprecated.pathname);
@ -4540,10 +4540,10 @@ int HAMLIB_API rig_set_split_mode(RIG *rig,
                  __LINE__, rig_strvfo(tx_vfo), rig_strrmode(tx_mode));
    }

-    // code below here should be dead code now -- but maybe we have  VFO situatiuon we need to handle
+    // code below here should be dead code now -- but maybe we have VFO situation we need to handle
    if (caps->rig_model == RIG_MODEL_NETRIGCTL)
    {
-        // special handlingt for netrigctl to avoid set_vfo
+        // special handling for netrigctl to avoid set_vfo
        retcode = caps->set_split_mode(rig, vfo, tx_mode, tx_width);
        ELAPSED2;
        RETURNFUNC(retcode);
@ -4830,7 +4830,7 @@ int HAMLIB_API rig_set_split_freq_mode(RIG *rig,

        HAMLIB_TRACE;
        retcode = caps->set_split_freq_mode(rig, vfo, tx_freq, tx_mode, tx_width);
-#if 0 // this verification seems to be causing bad behavior on some reigs
+#if 0 // this verification seems to be causing bad behavior on some rigs

        // we query freq after set to ensure it really gets done
        do
@ -5708,7 +5708,7 @@ int HAMLIB_API rig_get_ts(RIG *rig, vfo_t vfo, shortfreq_t *ts)
 * \brief set the antenna
 * \param rig   The rig handle
 * \param vfo   The target VFO
- * \param ant   The anntena to select
+ * \param ant   The antenna to select
 * \param option An option that the ant command for the rig recognizes
 *
 *  Select the antenna connector.
@ -7456,7 +7456,7 @@ int HAMLIB_API rig_cookie(RIG *rig, enum cookie_e cookie_cmd, char *cookie,
            date_strget(cookie, cookie_len, 0);
            size_t len = strlen(cookie);
            // add on our random number to ensure uniqueness
-            // The cookie should never be longer then HAMLIB_COOKIE_SIZE
+            // The cookie should never be longer than HAMLIB_COOKIE_SIZE
            SNPRINTF(cookie + len, HAMLIB_COOKIE_SIZE - len, " %d\n", rand());
            strcpy(cookie_save, cookie);
            time_last_used = time_curr;
--- a/src/token.h
+++ b/src/token.h
@ -71,7 +71,7 @@
 #define TOK_STOP_BITS   TOKEN_FRONTEND(22)
 /** \brief  Serial parity (format?) */
 #define TOK_PARITY      TOKEN_FRONTEND(23)
-/** \brief Serial Handshake (format?)  */
+/** \brief Serial Handshake (format?) */
 #define TOK_HANDSHAKE   TOKEN_FRONTEND(24)
 /** \brief Serial Req. To Send status */
 #define TOK_RTS_STATE   TOKEN_FRONTEND(25)
@ -89,7 +89,7 @@
 #define TOK_PTT_BITNUM        TOKEN_FRONTEND(34)
 /** \brief  PTT share with other applications */
 #define TOK_PTT_SHARE        TOKEN_FRONTEND(35)
-/** \brief  PTT share with other applications */
+/** \brief  Flush with read instead of TCFLUSH */
 #define TOK_FLUSHX        TOKEN_FRONTEND(36)
 /** \brief  Asynchronous data transfer support */
 #define TOK_ASYNC        TOKEN_FRONTEND(37)
@ -101,7 +101,7 @@
 */
 /* rx_range_list/tx_range_list, filters, announces, has(func,lvl,..) */

-/** \brief rig: ?? */
+/** \brief rig: VFO compensation in ppm */
 #define TOK_VFO_COMP    TOKEN_FRONTEND(110)
 /** \brief rig: Rig state poll interval in milliseconds */
 #define TOK_POLL_INTERVAL   TOKEN_FRONTEND(111)
@ -121,11 +121,13 @@
 #define TOK_AUTO_DISABLE_SCREENSAVER  TOKEN_FRONTEND(126)
 /** \brief rig: Disable Yaesu band select logic */
 #define TOK_DISABLE_YAESU_BANDSELECT  TOKEN_FRONTEND(127)
-/** \brief rig: Supporess get_freq on VFOB for satellite RIT tuning */
+/** \brief rig: Suppress get_freq on VFOB for satellite RIT tuning */
 #define TOK_TWIDDLE_TIMEOUT  TOKEN_FRONTEND(128)
-/** \brief rig: Supporess get_freq on VFOB for satellite RIT tuning */
+/** \brief rig: Suppress get_freq on VFOB for satellite RIT tuning */
 #define TOK_TWIDDLE_RIT  TOKEN_FRONTEND(129)
+/** \brief rig: Add Hz to VFOA/Main frequency set */
 #define TOK_OFFSET_VFOA  TOKEN_FRONTEND(130)
+/** \brief rig: Add Hz to VFOB/Sub frequency set */
 #define TOK_OFFSET_VFOB  TOKEN_FRONTEND(131)
 /*
 * rotator specific tokens
--- a/tests/ampctl_parse.c
+++ b/tests/ampctl_parse.c
@ -868,7 +868,7 @@ int ampctl_parse(AMP *my_amp, FILE *fin, FILE *fout, char *argv[], int argc)

        rp_getline("\nAmplifier command: ");

-        /* EOF (Ctl-D) received on empty input line, bail out gracefully. */
+        /* EOF (Ctrl-D) received on empty input line, bail out gracefully. */
        if (!input_line)
        {
            fprintf_flush(fout, "\n");
@ -952,7 +952,7 @@ int ampctl_parse(AMP *my_amp, FILE *fin, FILE *fout, char *argv[], int argc)
            char cmd_name[MAXNAMSIZ];

            /* if there is no terminating '\0' character in the source string,
-             * srncpy() doesn't add one even if the supplied length is less
+             * strncpy() doesn't add one even if the supplied length is less
             * than the destination array.  Truncate the source string here.
             */
            if (strlen(parsed_input[0] + 1) >= MAXNAMSIZ)
--- a/tests/testcookie.c
+++ b/tests/testcookie.c
@ -28,9 +28,9 @@ static int test1()
    else {printf("Test#1c Failed\n"); return 1;}

 #if 0
-    // after 1 second we should be able to get a coookie
+    // after 1 second we should be able to get a cookie
    // this means the cookie holder did not renew within 1 second
-    hl_usleep(1500 * 1000); // after 1 second we should be able to get a coookie
+    hl_usleep(1500 * 1000); // after 1 second we should be able to get a cookie

    retcode = rig_cookie(NULL, RIG_COOKIE_GET, cookie2, sizeof(cookie2));

@ -91,7 +91,7 @@ static int test3_invalid_input()
    char cookie[HAMLIB_COOKIE_SIZE];
    int n = 0;

-    /* Make sure any value smaller then HAMLIB_COOKIE_SIZE is rejected */
+    /* Make sure any value smaller than HAMLIB_COOKIE_SIZE is rejected */
    for (unsigned int i = 0; i < HAMLIB_COOKIE_SIZE; i++)
    {
        retcode = rig_cookie(NULL, RIG_COOKIE_GET, cookie, i);