Merge pull request #1268 from dforsi/fix/doxygen

Add/fix Doxygen comments

NEWS

@@ -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"

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.
 

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

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/
 

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;

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 */
 };

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.

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));
     }
 

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.
  */
 

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

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()

src/cache.c

@@ -26,6 +26,7 @@
 #define CHECK_RIG_ARG(r) (!(r) || !(r)->caps || !(r)->state.comm_state)
 
 /**
+ * \file cache.c
  * \addtogroup rig
  * @{
  */

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;

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

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)

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);