From 30c04fabd40334c6f44778e6f19f335f13ea96e6 Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Mon, 8 Feb 2021 12:38:23 -0600 Subject: [PATCH 1/4] Exclude amp_conf.h from Doxygen processing As amp_conf.h only contains private function declarations exclude it from Doxygen processing for now. --- doc/hamlib.cfg.in | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/hamlib.cfg.in b/doc/hamlib.cfg.in index e2225d8c6..f25cb6789 100644 --- a/doc/hamlib.cfg.in +++ b/doc/hamlib.cfg.in @@ -21,6 +21,8 @@ INPUT = @top_srcdir@/doc/index.doxygen \ @top_srcdir@/include/hamlib/ \ @top_srcdir@/src/ +EXCLUDE = @top_srcdir@/src/amp_conf.h + INCLUDE_PATH = @top_srcdir@/include EXAMPLE_PATH = @top_srcdir@/tests/testrig.c \ From b97b4218cb5729f03e6ce069e252b4c9e145d243 Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Mon, 8 Feb 2021 12:40:01 -0600 Subject: [PATCH 2/4] Update public API Doxygen comments in amp_conf.c --- src/amp_conf.c | 74 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 48 insertions(+), 26 deletions(-) diff --git a/src/amp_conf.c b/src/amp_conf.c index 21c898475..0d435d34e 100644 --- a/src/amp_conf.c +++ b/src/amp_conf.c @@ -109,7 +109,7 @@ static const struct confparams ampfrontend_serial_cfg_params[] = { RIG_CONF_END, NULL, } }; - +//! @cond Doxygen_Suppress /** * \brief Set amplifier state info from alpha input * \param amp @@ -295,8 +295,10 @@ int frontamp_set_conf(AMP *amp, token_t token, const char *val) return RIG_OK; } +//! @endcond +//! @cond Doxygen_Suppress /** * \brief Get data from amplifier state in alpha form * \param amp non-null @@ -430,6 +432,7 @@ int frontamp_get_conf(AMP *amp, token_t token, char *val) return RIG_OK; } +//! @endcond #ifdef XXREMOVEDXXC @@ -489,13 +492,20 @@ int HAMLIB_API amp_token_foreach(AMP *amp, /** - * \brief lookup conf token by its name, return pointer to confparams struct. - * \param amp - * \param name - * \return confparams or NULL + * \brief Query an amplifier configuration parameter token by its name. + * \param amp The #AMP handle. + * \param name Configuration parameter token name (C string). * - * lookup backend config table first, then fall back to frontend. - * TODO: should use Lex to speed it up, strcmp hurts! + * Use this function to get a pointer to the token in the #confparams + * structure. Searches the backend config params table first, then falls back + * to the frontend config params table. + * + * TODO: Should use Lex to speed it up, strcmp() hurts! + * + * \return A pointer to the token in the #confparams structure or NULL if #AMP + * is invalid or token not found (how can the caller know which occurred?). + * + * \sa amp_token_lookup() */ const struct confparams *HAMLIB_API amp_confparam_lookup(AMP *amp, const char *name) @@ -545,10 +555,16 @@ const struct confparams *HAMLIB_API amp_confparam_lookup(AMP *amp, /** - * \brief Simple lookup returning token id associated with name - * \param amp - * \param name - * \return token enum + * \brief Search for the token ID associated with an amplifier configuration parameter token name. + * \param amp The #AMP handle. + * \param name Configuration parameter token name (C string). + * + * Searches the backend and frontend configuration parameters tables for the + * token ID. + * + * \return The token ID value or RIG_CONF_END if the lookup failed. + * + * \sa amp_confparam_lookup() */ token_t HAMLIB_API amp_token_lookup(AMP *amp, const char *name) { @@ -568,16 +584,19 @@ token_t HAMLIB_API amp_token_lookup(AMP *amp, const char *name) /** - * \brief set a amplifier configuration parameter - * \param amp The amp handle - * \param token The parameter - * \param val The value to set the parameter to + * \brief Set an amplifier configuration parameter. + * \param amp The #AMP handle. + * \param token The token of the parameter to set. + * \param val The value to set the parameter to. * - * Sets a configuration parameter. + * Sets an amplifier configuration parameter to \a val. * - * \return RIG_OK if the operation has been successful, otherwise - * a negative value if an error occurred (in which case, cause is - * set appropriately). + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK The parameter was set successfully. + * \retval RIG_EINVAL The #AMP handle or token was invalid. + * \retval RIG_ENAVAIL amp_caps#set_conf() capability is not available. * * \sa amp_get_conf() */ @@ -620,16 +639,19 @@ int HAMLIB_API amp_set_conf(AMP *amp, token_t token, const char *val) /** - * \brief get the value of a configuration parameter - * \param amp The amp handle - * \param token The parameter - * \param val The location where to store the value of config \a token + * \brief Query the value of an amplifier configuration parameter. + * \param amp The #AMP handle. + * \param token The token of the parameter to query. + * \param val The location where to store the value of configuration \a token. * * Retrieves the value of a configuration parameter associated with \a token. * - * \return RIG_OK if the operation has been successful, otherwise - * a negative value if an error occurred (in which case, cause is - * set appropriately). + * \return RIG_OK if the operation has been successful, otherwise a **negative + * value** if an error occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK Querying the parameter was successful. + * \retval RIG_EINVAL The #AMP handle was invalid. + * \retval RIG_ENAVAIL amp_caps#get_conf() capability is not available. * * \sa amp_set_conf() */ From f4899caf179cfa5e15e3a4974541b82ed8bb5a1c Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Mon, 8 Feb 2021 12:41:40 -0600 Subject: [PATCH 3/4] Update public API Doxygen comments in amp_settings.c --- src/amp_settings.c | 48 +++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/src/amp_settings.c b/src/amp_settings.c index 7f29064e5..97cbb954f 100644 --- a/src/amp_settings.c +++ b/src/amp_settings.c @@ -1,20 +1,7 @@ -/** - * \addtogroup amplifier - * @{ - */ - -/** - * \file amp_settings.c - * \brief amplifiter func/level/parm interface - * \author Stephane Fillod - * \date 2000-2010 - * - * Hamlib interface is a frontend implementing wrapper functions. - */ - /* * Hamlib Interface - amplifier func/level/parm * Copyright (c) 2000-2010 by Stephane Fillod + * Copyright (c) 2020 by Mikael Nousiainen * * * This library is free software; you can redistribute it and/or @@ -33,6 +20,23 @@ * */ + +/** + * \addtogroup amplifier + * @{ + */ + +/** + * \file amp_settings.c + * \brief amplifiter func/level/parm interface + * \author Stephane Fillod + * \date 2000-2010 + * \author Mikael Nousiainen + * \date 2020 + * + * Hamlib interface is a frontend implementing wrapper functions. + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -44,17 +48,17 @@ /** - * \brief check retrieval ability of level settings - * \param amp The amp handle - * \param level The level settings + * \brief Check retrieval ability of level settings. + * \param amp The #AMP handle. + * \param level The level settings to check. * - * Checks if an amp is capable of *getting* a level setting. - * Since the \a level is an OR'ed bitwise argument, more than - * one level can be checked at the same time. + * Checks if an amplifier is capable of *getting* a level setting. Since the + * \a level is an OR'ed bitwise argument, more than one level can be checked + * at the same time. * - * EXAMPLE: if (amp_has_get_level(my_amp, AMP_LVL_SWR)) disp_SWR(); + * EXAMPLE: \code if (amp_has_get_level(my_amp, AMP_LVL_SWR)) disp_SWR();\endcode * - * \return a bit map of supported level settings that can be retrieved, + * \return A bit map of supported level settings that can be retrieved, * otherwise 0 if none supported. * * \sa amp_has_set_level(), amp_get_level() From 7b32e58a7634fbb445d7f59bfcdcaecb3c83c8ac Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Mon, 8 Feb 2021 12:48:47 -0600 Subject: [PATCH 4/4] Exclude ampclass.h from Doxygen processing Exclude ampclass.h from Doxygen processing for now. --- doc/hamlib.cfg.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/hamlib.cfg.in b/doc/hamlib.cfg.in index f25cb6789..5e9b54d2d 100644 --- a/doc/hamlib.cfg.in +++ b/doc/hamlib.cfg.in @@ -21,7 +21,8 @@ INPUT = @top_srcdir@/doc/index.doxygen \ @top_srcdir@/include/hamlib/ \ @top_srcdir@/src/ -EXCLUDE = @top_srcdir@/src/amp_conf.h +EXCLUDE = @top_srcdir@/src/amp_conf.h \ + @top_srcdir@/include/hamlib/ampclass.h INCLUDE_PATH = @top_srcdir@/include