[Hamlib-commits] Hamlib -- Ham radio control libraries branch master updated. 8d57058412359636ec21df82d0d8ddb5371e868b

[Nate B. <n0...@us...>]

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  8d57058412359636ec21df82d0d8ddb5371e868b (commit)
       via  171aa9e89a82b875422183c07b2ca5de2d4fdecd (commit)
      from  62bcb66865a863c77967a0b4142bf668ac064c44 (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 8d57058412359636ec21df82d0d8ddb5371e868b
Merge: 62bcb668 171aa9e8
Author: Nate Bargmann <n0...@n0...>
Date:   Sun Feb 21 13:13:03 2021 -0600

    Merge pull request #557 from N0NB/doxygen_work
    
    Update and refine Doxygen comments for extension levels, etc.


commit 171aa9e89a82b875422183c07b2ca5de2d4fdecd
Author: Nate Bargmann <n0...@n0...>
Date:   Sun Feb 21 13:07:45 2021 -0600

    Update and refine Doxygen comments for extension levels, etc.

diff --git a/include/hamlib/amplifier.h b/include/hamlib/amplifier.h
index 05ea5eb4..15624e6b 100644
--- a/include/hamlib/amplifier.h
+++ b/include/hamlib/amplifier.h
@@ -253,8 +253,8 @@ struct amp_caps
   setting_t levels;
   unsigned ext_levels;
 //! @endcond
-  const struct confparams *extlevels;         /*!< Extension levels structure.  */
-  const struct confparams *extparms;          /*!< Extension parameters structure.  */
+  const struct confparams *extlevels;         /*!< Extension levels list.  \sa extamp.c */
+  const struct confparams *extparms;          /*!< Extension parameters list.  \sa extamp.c */
 
   const char *macro_name;                     /*!< Amplifier model macro name. */
 };
diff --git a/include/hamlib/rotator.h b/include/hamlib/rotator.h
index e23c3410..1637a364 100644
--- a/include/hamlib/rotator.h
+++ b/include/hamlib/rotator.h
@@ -383,9 +383,9 @@ struct rot_caps {
     gran_t level_gran[RIG_SETTING_MAX]; /*!< level granularity (i.e. steps). */
     gran_t parm_gran[RIG_SETTING_MAX];  /*!< parm granularity (i.e. steps). */
 
-    const struct confparams *extparms;  /*!< Extension parameter list, \sa ext.c. */
-    const struct confparams *extlevels; /*!< Extension level list, \sa ext.c. */
-    const struct confparams *extfuncs;  /*!< Extension func list, \sa ext.c. */
+    const struct confparams *extparms;  /*!< Extension parameters list, \sa rot_ext.c. */
+    const struct confparams *extlevels; /*!< Extension levels list, \sa rot_ext.c. */
+    const struct confparams *extfuncs;  /*!< Extension functions list, \sa rot_ext.c. */
     int *ext_tokens;                    /*!< Extension token list. */
 
     /*
diff --git a/src/amplifier.c b/src/amplifier.c
index 9aa5056e..60d30e08 100644
--- a/src/amplifier.c
+++ b/src/amplifier.c
@@ -220,7 +220,9 @@ AMP *HAMLIB_API amp_init(amp_model_t amp_model)
 
     /*
      * populate the amp->state
-     * TODO: read the Preferences here!
+     */
+    /**
+     * \todo Read the Preferences here!
      */
     rs = &amp->state;
 
diff --git a/src/extamp.c b/src/extamp.c
index a0dbd797..e9289035 100644
--- a/src/extamp.c
+++ b/src/extamp.c
@@ -29,6 +29,7 @@
 /**
  * \file extamp.c
  * \brief Amplifier extension parameters and levels interface.
+ *
  * \author Michael Black
  * \date 2019
  *
@@ -55,8 +56,8 @@
 
 
 /**
- * \brief Executes \a cfunc on all the elements stored in the
- * amp_caps::extlevels extension levels table.
+ * \brief Executes \a cfunc on all the elements stored in the amp_caps::extlevels
+ * extension levels table.
  *
  * \param amp The #AMP handle.
  * \param cfunc Callback function of each amp_caps::extlevels.
@@ -65,8 +66,8 @@
  * The callback function \a cfunc is called until it returns a value which is
  * not strictly positive.
  *
- * \returns A zero value which means a normal end of iteration, or a negative
- * value which means an abnormal end,
+ * \returns A zero value which means a normal end of iteration, or a
+ * **negative value** which means an abnormal end,
  *
  * \retval RIG_OK All extension levels elements successfully processed.
  * \retval RIG_EINVAL \a amp or \a cfunc is NULL or inconsistent.
@@ -117,7 +118,7 @@ int HAMLIB_API amp_ext_level_foreach(AMP *amp,
  * strictly positive.
  *
  * \returns A zero value which means a normal end of iteration, or a
- * negative value which means an abnormal end.
+ * **negative value** which means an abnormal end.
  *
  * \retval RIG_OK All extension parameters elements successfully processed.
  * \retval RIG_EINVAL \a amp or \a cfunc is NULL or inconsistent.
@@ -163,15 +164,18 @@ int HAMLIB_API amp_ext_parm_foreach(AMP *amp,
  * \param amp The #AMP handle.
  * \param name The extension levels or parameters token name.
  *
- * Searches the amp_caps::extlevels table first and then falls back to
- * amp_caps::extparms.
+ * Searches the amp_caps::extlevels table and then the amp_caps::extparms
+ * table for the token by its name.
+ *
+ * \note As this function is called by amp_ext_token_lookup(), it can be
+ * considered a lower level API.
  *
  * \return A pointer to the containing #confparams structure member or NULL if
  * nothing found or if \a amp is NULL or inconsistent.
  *
  * \sa amp_ext_token_lookup()
  *
- * TODO: should use Lex to speed it up, strcmp() hurts!
+ * \todo Should use Lex to speed it up, strcmp() hurts!
  */
 const struct confparams *HAMLIB_API amp_ext_lookup(AMP *amp, const char *name)
 {
@@ -205,13 +209,14 @@ const struct confparams *HAMLIB_API amp_ext_lookup(AMP *amp, const char *name)
 
 
 /**
- * \brief Lookup an extension levels or parameters token by its constant value
- * and return a pointer to the #confparams structure member.
+ * \brief Search for an extension levels or parameters token by its constant
+ * value and return a pointer to the #confparams structure member.
  *
  * \param amp The #AMP handle.
  * \param token The token value (constant).
  *
- * Searches the amp_caps::extlevels table first and then falls back to amp_caps::extparms.
+ * Searches the amp_caps::extlevels table first and then the
+ * amp_caps::extparms for the token by its constant value.
  *
  * \return A pointer to the containing #confparams structure member or NULL if
  * nothing found or if \a amp is NULL or inconsistent.
@@ -248,11 +253,14 @@ const struct confparams *HAMLIB_API amp_ext_lookup_tok(AMP *amp, token_t token)
 
 
 /**
- * \brief Simple lookup returning the extension token ID associated with \a
- * name.
+ * \brief Simple search returning the extension token ID associated with
+ * \a name.
  *
  * \param amp The #AMP handle.
- * \param name The name string to search.
+ * \param name The token name string to search.
+ *
+ * \note As this function calls amp_ext_lookup(), it can be considered a
+ * higher level API.
  *
  * \return The token ID or RIG_CONF_END if there is a lookup failure.
  *
diff --git a/src/rot_ext.c b/src/rot_ext.c
index b3b19c2f..73aa4468 100644
--- a/src/rot_ext.c
+++ b/src/rot_ext.c
@@ -26,12 +26,16 @@
 
 /**
  * \file rot_ext.c
- * \brief Extension request parameter interface for rotators
+ * \brief Rotator extension parameters and levels interface.
  *
- * An open-ended set of extension parameters, functions and levels are available
- * for each rotator, as provided in the rotcaps extparms, extfuncs and extlevels lists.
- * These provide a way to work with rotator-specific functions that don't fit into the
- * basic "virtual rotator" of Hamlib.
+ * \author Mikael Nousiainen
+ * \date 2020
+ *
+ * An open-ended set of extension parameters, functions and levels are
+ * available for each rotator, as provided in the rot_caps::extparms,
+ * rot_caps::extfuncs and rot_caps::extlevels lists.  These provide a way to
+ * work with rotator-specific functions that don't fit into the basic "virtual
+ * rotator" of Hamlib.
  */
 
 #ifdef HAVE_CONFIG_H
@@ -71,15 +75,21 @@ static int rot_has_ext_token(ROT *rot, token_t token)
 
 
 /**
- * \param rot The rotator handle
- * \param cfunc callback function of each extfunc
- * \param data cookie to be passed to \a cfunc callback
- * \brief Executes cfunc on all the elements stored in the extfuncs table
+ * \brief Executes \a cfunc on all the elements stored in the
+ * rot_caps::extfuncs table.
+ *
+ * \param rot The #ROT handle.
+ * \param cfunc Callback function of each rot_caps::extfunc.
+ * \param data Cookie to be passed to the callback function \a cfunc.
  *
  * The callback \a cfunc is called until it returns a value which is not
- * strictly positive.  A zero value means a normal end of iteration, and a
- * negative value an abnormal end, which will be the return value of
- * rot_ext_func_foreach.
+ * strictly positive.
+ *
+ * \returns A zero value means a normal end of iteration, or a **negative
+ * value** which means an abnormal end.
+ *
+ * \retval RIG_OK All extension functions elements successfully processed.
+ * \retval RIG_EINVAL \a rot or \a cfunc is NULL or inconsistent.
  */
 int HAMLIB_API rot_ext_func_foreach(ROT *rot,
                                     int (*cfunc)(ROT *,
@@ -121,15 +131,21 @@ int HAMLIB_API rot_ext_func_foreach(ROT *rot,
 
 
 /**
- * \param rot The rotator handle
- * \param cfunc callback function of each extlevel
- * \param data cookie to be passed to \a cfunc callback
- * \brief Executes cfunc on all the elements stored in the extlevels table
+ * \brief Executes \a cfunc on all the elements stored in the
+ * rot_caps::extlevels extension levels table.
+ *
+ * \param rot The #ROT handle.
+ * \param cfunc Callback function of each rot_caps::extlevels.
+ * \param data Cookie to be passed to the callback function \a cfunc.
  *
  * The callback \a cfunc is called until it returns a value which is not
- * strictly positive.  A zero value means a normal end of iteration, and a
- * negative value an abnormal end, which will be the return value of
- * rot_ext_level_foreach.
+ * strictly positive.
+ *
+ * \returns A zero value which means a normal end of iteration, or a
+ * **negative value** which means an abnormal end.
+ *
+ * \retval RIG_OK All extension levels elements successfully processed.
+ * \retval RIG_EINVAL \a rot or \a cfunc is NULL or inconsistent.
  */
 int HAMLIB_API rot_ext_level_foreach(ROT *rot,
                                      int (*cfunc)(ROT *,
@@ -171,15 +187,21 @@ int HAMLIB_API rot_ext_level_foreach(ROT *rot,
 
 
 /**
- * \param rot The rotator handle
- * \param cfunc callback function of each extparm
- * \param data cookie to be passed to \a cfunc callback
- * \brief Executes cfunc on all the elements stored in the extparms table
+ * \brief Executes \a cfunc on all the elements stored in the
+ * rot_caps::extparms extension parameters table.
  *
- * The callback \a cfunc is called until it returns a value which is not
- * strictly positive.  A zero value means a normal end of iteration, and a
- * negative value an abnormal end, which will be the return value of
- * rot_ext_parm_foreach.
+ * \param rot The #ROT handle.
+ * \param cfunc callback function of each rot_caps::extparms.
+ * \param data Cookie to be passed to the callback function \a cfunc.
+ *
+ * The callback function \a cfunc is called until it returns a value which is not
+ * strictly positive.
+ *
+ * \returns A zero value which means a normal end of iteration, or a
+ * **negative value** which means an abnormal end.
+ *
+ * \retval RIG_OK All extension parameters elements successfully processed.
+ * \retval RIG_EINVAL \a rot or \a cfunc is NULL or inconsistent.
  */
 int HAMLIB_API rot_ext_parm_foreach(ROT *rot,
                                     int (*cfunc)(ROT *,
@@ -221,15 +243,24 @@ int HAMLIB_API rot_ext_parm_foreach(ROT *rot,
 
 
 /**
- * \param rot
- * \param name
- * \brief lookup ext token by its name, return pointer to confparams struct.
+ * \brief Lookup an extension functions, levels, or parameters token by its
+ * name and return a pointer to the containing #confparams structure member.
+ *
+ * \param rot The #ROT handle.
+ * \param name The extension functions, levels, or parameters token name.
+ *
+ * Searches the rot_caps::extlevels, rot_caps::extfuncs and the
+ * rot_caps::extparms tables in order for the token by its name.
  *
- * Lookup extlevels table, then extfuncs, then extparms.
+ * \note As this function is called by rot_ext_token_lookup(), it can be
+ * considered a lower level API.
  *
- * Returns NULL if nothing found
+ * \return A pointer to the containing #confparams structure member or NULL if
+ * nothing found or if \a rot is NULL or inconsistent.
  *
- * TODO: should use Lex to speed it up, strcmp hurts!
+ * \sa rot_ext_token_lookup()
+ *
+ * \todo Should use Lex to speed it up, strcmp() hurts!
  */
 const struct confparams *HAMLIB_API rot_ext_lookup(ROT *rot, const char *name)
 {
@@ -270,13 +301,18 @@ const struct confparams *HAMLIB_API rot_ext_lookup(ROT *rot, const char *name)
 }
 
 /**
- * \param rot
- * \param token
- * \brief lookup ext token, return pointer to confparams struct.
+ * \brief Searches for an extension levels, functions, or parameters token by
+ * its constant value and return a pointer to the #confparams structure
+ * member.
+ *
+ * \param rot The #ROT handle.
+ * \param token The token value (constant).
  *
- * lookup extlevels table first, then extfuncs, then fall back to extparms.
+ * Searches the rot_caps::extlevels, rot_caps::extfuncs, and the
+ * rot_caps::extparms tables in order for the token by its constant value.
  *
- * Returns NULL if nothing found
+ * \return A pointer to the containing #confparams structure member or NULL if
+ * nothing found or if \a rot is NULL or inconsistent.
  */
 const struct confparams *HAMLIB_API rot_ext_lookup_tok(ROT *rot, token_t token)
 {
@@ -318,9 +354,18 @@ const struct confparams *HAMLIB_API rot_ext_lookup_tok(ROT *rot, token_t token)
 
 
 /**
- * \param rot
- * \param name
- * \brief Simple lookup returning token id associated with name
+ * \brief Simple search returning the extension token ID associated with
+ * \a name.
+ *
+ * \param rot The #ROT handle.
+ * \param name The token name string to search.
+ *
+ * \note As this function calls rot_ext_lookup(), it can be considered a
+ * higher level API.
+ *
+ * \return The token ID or RIG_CONF_END if there is a lookup failure.
+ *
+ * \sa rot_ext_lookup()
  */
 token_t HAMLIB_API rot_ext_token_lookup(ROT *rot, const char *name)
 {
diff --git a/src/rotator.c b/src/rotator.c
index 159b85c7..e89d3b33 100644
--- a/src/rotator.c
+++ b/src/rotator.c
@@ -251,7 +251,9 @@ ROT *HAMLIB_API rot_init(rot_model_t rot_model)
 
     /*
      * populate the rot->state
-     * TODO: read the Preferences here!
+     */
+    /**
+     * \todo Read the Preferences here!
      */
     rs = &rot->state;
 

-----------------------------------------------------------------------

Summary of changes:
 include/hamlib/amplifier.h |   4 +-
 include/hamlib/rotator.h   |   6 +--
 src/amplifier.c            |   4 +-
 src/extamp.c               |  36 ++++++++-----
 src/rot_ext.c              | 127 ++++++++++++++++++++++++++++++---------------
 src/rotator.c              |   4 +-
 6 files changed, 119 insertions(+), 62 deletions(-)


hooks/post-receive
-- 
Hamlib -- Ham radio control libraries