diff --git a/doc/hamlib.cfg.in b/doc/hamlib.cfg.in index e2225d8c6..5e9b54d2d 100644 --- a/doc/hamlib.cfg.in +++ b/doc/hamlib.cfg.in @@ -21,6 +21,9 @@ INPUT = @top_srcdir@/doc/index.doxygen \ @top_srcdir@/include/hamlib/ \ @top_srcdir@/src/ +EXCLUDE = @top_srcdir@/src/amp_conf.h \ + @top_srcdir@/include/hamlib/ampclass.h + INCLUDE_PATH = @top_srcdir@/include EXAMPLE_PATH = @top_srcdir@/tests/testrig.c \ 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() */ 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()