From 171aa9e89a82b875422183c07b2ca5de2d4fdecd Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Sun, 21 Feb 2021 13:07:45 -0600 Subject: [PATCH] Update and refine Doxygen comments for extension levels, etc. --- 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(-) diff --git a/include/hamlib/amplifier.h b/include/hamlib/amplifier.h index 05ea5eb4b..15624e6b2 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 e23c3410a..1637a3647 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 9aa5056e8..60d30e080 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 = &->state; diff --git a/src/extamp.c b/src/extamp.c index a0dbd7973..e9289035e 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 b3b19c2f9..73aa44688 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. * - * Lookup extlevels table, then extfuncs, then extparms. + * \param rot The #ROT handle. + * \param name The extension functions, levels, or parameters token name. * - * Returns NULL if nothing found + * Searches the rot_caps::extlevels, rot_caps::extfuncs and the + * rot_caps::extparms tables in order for the token by its name. * - * TODO: should use Lex to speed it up, strcmp hurts! + * \note As this function is called by rot_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 rot is NULL or inconsistent. + * + * \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. * - * lookup extlevels table first, then extfuncs, then fall back to extparms. + * \param rot The #ROT handle. + * \param token The token value (constant). * - * Returns NULL if nothing found + * Searches the rot_caps::extlevels, rot_caps::extfuncs, and the + * rot_caps::extparms tables in order for the token by its constant value. + * + * \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 159b85c77..e89d3b332 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;