From 2bf4a49f5da1595c71860e65be7af473de4f01b6 Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Fri, 12 Feb 2021 12:46:01 -0600 Subject: [PATCH] Update Doxygen comments for amplifier group Aim for consistency in Doxygen comments structure. --- include/hamlib/amplifier.h | 28 +++++++---- include/hamlib/amplist.h | 62 ++++++++++++----------- src/amp_conf.c | 32 +++++++----- src/amp_settings.c | 7 ++- src/amplifier.c | 59 ++++++++++++++-------- src/extamp.c | 100 ++++++++++++++++++++++++------------- 6 files changed, 177 insertions(+), 111 deletions(-) diff --git a/include/hamlib/amplifier.h b/include/hamlib/amplifier.h index 067ca0260..05ea5eb4b 100644 --- a/include/hamlib/amplifier.h +++ b/include/hamlib/amplifier.h @@ -31,9 +31,10 @@ */ /** - * \file amplifier.h * \brief Hamlib amplifier data structures. * + * \file amplifier.h + * * This file contains the data structures and declarations for the Hamlib * amplifier Application Programming Interface (API). * @@ -51,9 +52,10 @@ struct amp_state; /** - * \typedef typedef struct amp AMP * \brief Main amplifier handle type definition. * + * \typedef typedef struct amp AMP + * * The #AMP handle is returned by amp_init() and is passed as a parameter to * every amplifier specific API call. * @@ -63,10 +65,11 @@ typedef struct amp AMP; /** - * \typedef typedef float swr_t * \brief Type definition for * SWR (Standing Wave Ratio). * + * \typedef typedef float swr_t + * * The \a swr_t type is used as a parameter for the amp_get_swr() function. * * The unit of \a swr_t is 1.0 to the maximum value reported by the amplifier's @@ -78,7 +81,6 @@ typedef float swr_t; /** - * \typedef typedef float tune_value_t * \brief Type definition for the * transmatch * tuning values of @@ -86,6 +88,8 @@ typedef float swr_t; * and * inductance. * + * \typedef typedef float tune_value_t + * * The \a tune_value_t type is used as a parameter for amp_get_level(). * * The unit of \a tune_value_t is @@ -163,8 +167,9 @@ enum amp_level_e //! @endcond /** + * \brief Amplifier capabilities. + * * \struct amp_caps - * \brief Amplifier capabilities * * The main idea of this struct is that it will be defined by the backend * amplifier driver and will remain read-only for the application. Fields @@ -248,16 +253,17 @@ struct amp_caps setting_t levels; unsigned ext_levels; //! @endcond - const struct confparams *extlevels; /*!< Extra levels structure. */ - const struct confparams *extparms; /*!< Extra parameters structure. */ + const struct confparams *extlevels; /*!< Extension levels structure. */ + const struct confparams *extparms; /*!< Extension parameters structure. */ const char *macro_name; /*!< Amplifier model macro name. */ }; /** + * \brief Amplifier state structure. + * * \struct amp_state - * \brief Amplifier state structure * * This structure contains live data, as well as a copy of capability fields * that may be updated, i.e. customized while the #AMP handle is instantiated. @@ -288,8 +294,9 @@ struct amp_state /** + * \brief Master amplifier structure. + * * \struct amp - * \brief Master amplifier structure * * Master amplifier data structure acting as the #AMP handle for the * controlled amplifier. A pointer to this structure is returned by the @@ -423,9 +430,10 @@ extern HAMLIB_EXPORT(const char *) amp_strlevel(setting_t); /** - * \def amp_debug * \brief Convenience macro for generating debugging messages. * + * \def amp_debug + * * This is an alias of the rig_debug() function call and is used in the same * manner. */ diff --git a/include/hamlib/amplist.h b/include/hamlib/amplist.h index b8d094d8d..018997c7b 100644 --- a/include/hamlib/amplist.h +++ b/include/hamlib/amplist.h @@ -36,21 +36,22 @@ */ /** - * \file amplist.h - * \brief Hamlib amplifier model definitions. + * \brief Hamlib amplifier model definitions. * - * This file contains amplifier model definitions for the Hamlib amplifier - * Application Programming Interface (API). Each distinct amplifier type has - * a unique model number (ID) and is used by Hamlib to identify and - * distinguish between the different hardware drivers. The exact model - * numbers can be acquired using the macros in this file. To obtain a list of - * supported amplifier branches, one can use the statically defined - * AMP_BACKEND_LIST macro. To obtain a full list of supported amplifiers - * (including each model in every branch), the foreach_opened_amp() API - * function can be used. + * \file amplist.h * - * The model number, or ID, is used to tell Hamlib which amplifier the client - * wishes to use. It is done with the amp_init() API call. + * This file contains amplifier model definitions for the Hamlib amplifier + * Application Programming Interface (API). Each distinct amplifier type has + * a unique model number (ID) and is used by Hamlib to identify and + * distinguish between the different hardware drivers. The exact model + * numbers can be acquired using the macros in this file. To obtain a list of + * supported amplifier branches, one can use the statically defined + * AMP_BACKEND_LIST macro. To obtain a full list of supported amplifiers + * (including each model in every branch), the foreach_opened_amp() API + * function can be used. + * + * The model number, or ID, is used to tell Hamlib which amplifier the client + * wishes to use. It is done with the amp_init() API call. */ @@ -63,19 +64,20 @@ */ /** - * \def AMP_MODEL_DUMMY - * \brief A macro that returns the model number for the dummy backend. + * \brief A macro that returns the model number for the dummy backend. * - * The dummy backend, as the name suggests, is a backend which performs no - * hardware operations and always behaves as one would expect. It can be - * thought of as a hardware simulator and is very useful for testing client - * applications. + * \def AMP_MODEL_DUMMY * - * \def AMP_MODEL_NETAMPCTL - * \brief A macro that returns the model number for the netampctl backend. + * The dummy backend, as the name suggests, is a backend which performs no + * hardware operations and always behaves as one would expect. It can be + * thought of as a hardware simulator and is very useful for testing client + * applications. * - * This backend allows use of the ampctld daemon through the normal - * Hamlib API. + * \def AMP_MODEL_NETAMPCTL + * \brief A macro that returns the model number for the netampctl backend. + * + * This backend allows use of the ampctld daemon through the normal + * Hamlib API. */ //! @cond Doxygen_Suppress #define AMP_DUMMY 0 @@ -90,11 +92,12 @@ */ /** - * \def AMP_MODEL_ELECRAFT_KPA1500 - * \brief A macro that returns the model number of the kpa1500 backend. + * \brief A macro that returns the model number of the kpa1500 backend. * - * The kpa1500 backend can be used with amplifiers that support the Elecraft - * KPA-1500 protocol. + * \def AMP_MODEL_ELECRAFT_KPA1500 + * + * The kpa1500 backend can be used with amplifiers that support the Elecraft + * KPA-1500 protocol. */ //! @cond Doxygen_Suppress #define AMP_ELECRAFT 2 @@ -104,8 +107,9 @@ //#define AMP_MODEL_ELECRAFT_KPA500 AMP_MAKE_MODEL(AMP_ELECRAFT, 2) /** - * \typedef typedef int amp_model_t - * \brief Convenience type definition for amplifier model. + * \brief Convenience type definition for amplifier model. + * + * \typedef typedef int amp_model_t */ typedef int amp_model_t; diff --git a/src/amp_conf.c b/src/amp_conf.c index 0d435d34e..1e1390e4e 100644 --- a/src/amp_conf.c +++ b/src/amp_conf.c @@ -493,19 +493,21 @@ int HAMLIB_API amp_token_foreach(AMP *amp, /** * \brief Query an amplifier configuration parameter token by its name. + * * \param amp The #AMP handle. - * \param name Configuration parameter token name (C string). + * \param name Configuration parameter token name string. * * 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?). + * \return A pointer to the token in the #confparams structure or NULL if + * \a amp is invalid or \a token not found (how can the caller know which + * occurred?). * * \sa amp_token_lookup() + * + * TODO: Should use Lex to speed it up, strcmp() hurts! */ const struct confparams *HAMLIB_API amp_confparam_lookup(AMP *amp, const char *name) @@ -555,9 +557,11 @@ const struct confparams *HAMLIB_API amp_confparam_lookup(AMP *amp, /** - * \brief Search for the token ID associated with an amplifier configuration parameter token name. + * \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). + * \param name Configuration parameter token name string. * * Searches the backend and frontend configuration parameters tables for the * token ID. @@ -585,6 +589,7 @@ token_t HAMLIB_API amp_token_lookup(AMP *amp, const char *name) /** * \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. @@ -595,7 +600,7 @@ token_t HAMLIB_API amp_token_lookup(AMP *amp, const char *name) * 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_EINVAL \a amp or \a token was invalid. * \retval RIG_ENAVAIL amp_caps#set_conf() capability is not available. * * \sa amp_get_conf() @@ -640,17 +645,18 @@ int HAMLIB_API amp_set_conf(AMP *amp, token_t token, const char *val) /** * \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. + * \param amp The #AMP handle. + * \param token The token of the parameter to query. + * \param val The location where to store the value of the 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). * * \retval RIG_OK Querying the parameter was successful. - * \retval RIG_EINVAL The #AMP handle was invalid. + * \retval RIG_EINVAL \a amp is NULL or 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 97cbb954f..81aeda236 100644 --- a/src/amp_settings.c +++ b/src/amp_settings.c @@ -27,14 +27,16 @@ */ /** + * \brief Amplifier function/level/parameter interface. + * * \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. + * This Hamlib interface is a frontend implementing wrapper functions. */ #ifdef HAVE_CONFIG_H @@ -49,6 +51,7 @@ /** * \brief Check retrieval ability of level settings. + * * \param amp The #AMP handle. * \param level The level settings to check. * diff --git a/src/amplifier.c b/src/amplifier.c index bf2eecf14..7d6d711eb 100644 --- a/src/amplifier.c +++ b/src/amplifier.c @@ -134,17 +134,18 @@ static int remove_opened_amp(AMP *amp) #ifdef XXREMOVEDXX /** - * \brief execs cfunc() on each opened amp - * \param cfunc The function to be executed on each amp - * \param data Data pointer to be passed to cfunc() + * \brief Executess cfunc() on each #AMP handle. * - * Calls cfunc() function for each opened amp. The contents of the opened - * amp table is processed in random order according to a function pointed to - * by \a cfunc, which is called with two arguments, the first pointing to the - * #AMP handle, the second to a data pointer \a data. + * \param cfunc The function to be executed on each #AMP handle. + * \param data Data pointer to be passed to cfunc() * - * If \a data is not needed, then it can be set to NULL. The processing of - * the opened amp table is stopped when cfunc() returns 0. + * Calls cfunc() function for each #AMP handle. The contents of the opened + * #AMP table is processed in random order according to a function pointed to + * by \a cfunc, which is called with two arguments, the first pointing to the + * #AMP handle, the second to a data pointer \a data. + * + * If \a data is not needed, then it can be set to NULL. The processing of + * the opened amp table is stopped when cfunc() returns 0. * \internal * * \return always RIG_OK. @@ -169,8 +170,9 @@ int foreach_opened_amp(int (*cfunc)(AMP *, rig_ptr_t), rig_ptr_t data) /** - * \brief Allocate a new #AMP handle - * \param amp_model The amplifier model for this new handle + * \brief Allocate a new #AMP handle. + * + * \param amp_model The amplifier model for this new handle. * * Allocates a new #AMP handle and initializes the associated data * for \a amp_model (see amplist.h or `ampctl -l`). @@ -280,7 +282,8 @@ AMP *HAMLIB_API amp_init(amp_model_t amp_model) /** * \brief Open the communication channel to the amplifier. - * \param amp The #AMP handle of the amplifier to be opened + * + * \param amp The #AMP handle of the amplifier to be opened. * * Opens the communication channel to an amplifier for which the #AMP handle * has been passed. @@ -414,6 +417,7 @@ int HAMLIB_API amp_open(AMP *amp) /** * \brief Close the communication channel to the amplifier. + * * \param amp The #AMP handle of the amplifier to be closed. * * Closes the communication channel to an amplifier for which the #AMP @@ -496,6 +500,7 @@ int HAMLIB_API amp_close(AMP *amp) /** * \brief Release an #AMP handle and free associated memory. + * * \param amp The #AMP handle to be released. * * Releases an #AMP handle for which the communications channel has been @@ -541,11 +546,12 @@ int HAMLIB_API amp_cleanup(AMP *amp) /** - * \brief Reset the amplifier - * \param amp The #AMP handle + * \brief Reset the amplifier. + * + * \param amp The #AMP handle. * \param reset The reset operation to perform. * - * Perform a reset of the amplifier. + * Perform a reset of the amplifier. * * \return RIG_OK if the operation has been successful, otherwise a **negative * value** if an error occurred (in which case, cause is set appropriately). @@ -578,6 +584,7 @@ int HAMLIB_API amp_reset(AMP *amp, amp_reset_t reset) /** * \brief Query the operating frequency of the amplifier. + * * \param amp The #AMP handle. * \param freq The variable to store the operating frequency. * @@ -616,6 +623,7 @@ int HAMLIB_API amp_get_freq(AMP *amp, freq_t *freq) /** * \brief Set the operating frequency of the amplifier. + * * \param amp The #AMP handle. * \param freq The operating frequency. * @@ -655,6 +663,7 @@ int HAMLIB_API amp_set_freq(AMP *amp, freq_t freq) /** * \brief Query general information from the amplifier. + * * \param amp The #AMP handle. * * Retrieves some general information from the amplifier. This can include @@ -662,7 +671,8 @@ int HAMLIB_API amp_set_freq(AMP *amp, freq_t freq) * * \return A pointer to static memory containing an ASCII nul terminated * string (C string) if the operation has been successful, otherwise NULL if - * an error occurred or the amp_caps#get_info() capability is not available. + * \a amp is NULL or invalid or the amp_caps#get_info() capability is not + * available. */ const char *HAMLIB_API amp_get_info(AMP *amp) { @@ -684,6 +694,7 @@ const char *HAMLIB_API amp_get_info(AMP *amp) /** * \brief Query the value of a requested level. + * * \param amp The #AMP handle. * \param level The requested level. * \param val The variable to store the \a level value. @@ -718,12 +729,13 @@ int HAMLIB_API amp_get_level(AMP *amp, setting_t level, value_t *val) /** - * \brief Query the value of a requested extra level token. - * \param amp The #AMP handle. - * \param level The requested extra level token. - * \param val The variable to store the extra \a level token value. + * \brief Query the value of a requested extension levels token. * - * Query the \a val corresponding to the extra \a level token. + * \param amp The #AMP handle. + * \param level The requested extension levels token. + * \param val The variable to store the extension \a level token value. + * + * Query the \a val corresponding to the extension \a level token. * * \return RIG_OK if the operation was successful, otherwise a **negative * value** if an error occurred (in which case, cause is set appropriately). @@ -753,7 +765,9 @@ int HAMLIB_API amp_get_ext_level(AMP *amp, token_t level, value_t *val) /** - * \brief Turn the amplifier On or Off or toggle the Standby or Operate status. + * \brief Turn the amplifier On or Off or toggle the Standby or Operate + * status. + * * \param amp The #AMP handle * \param status The #powerstat_t setting. * @@ -790,6 +804,7 @@ int HAMLIB_API amp_set_powerstat(AMP *amp, powerstat_t status) /** * \brief Query the power or standby status of the amplifier. + * * \param amp The #AMP handle. * \param status The variable to store the amplifier \a status. * diff --git a/src/extamp.c b/src/extamp.c index 078b76ead..300e3429c 100644 --- a/src/extamp.c +++ b/src/extamp.c @@ -27,13 +27,16 @@ */ /** - * \file ext.c - * \brief Extension request parameter interface + * \file extamp.c + * \brief Amplifier extension parameters and levels interface. + * \author Michael Black + * \date 2019 * * An open-ended set of extension parameters and levels are available for each - * amp, as provided in the ampcaps extparms and extlevels lists. These - * provide a way to work with amp-specific functions that don't fit into the - * basic "virtual amp" of Hamlib. See amplifiers/kpa.c for an example. + * amplifier, as provided in the amp_caps::extparms and amp_caps::extlevels + * lists. These provide a way to work with amplifier-specific functions that + * don't fit into the basic "virtual amplifier" of Hamlib. See + * `amplifiers/elecraft/kpa.c` for an example. */ #ifdef HAVE_CONFIG_H @@ -52,15 +55,21 @@ /** - * \param amp The amp 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 + * amp_caps::extlevels extension levels 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 - * amp_ext_level_foreach. + * \param amp The #AMP handle. + * \param cfunc Callback function of each amp_caps::extlevels. + * \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 levels elements successfully processed. + * \retval RIG_EINVAL \a amp or \a cfunc is NULL or inconsistent. */ int HAMLIB_API amp_ext_level_foreach(AMP *amp, int (*cfunc)(AMP *, @@ -97,15 +106,21 @@ int HAMLIB_API amp_ext_level_foreach(AMP *amp, /** - * \param amp The amp 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 + * amp_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 - * amp_ext_parm_foreach. + * \param amp The #AMP handle. + * \param cfunc Callback function of each amp_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 amp or \a cfunc is NULL or inconsistent. */ int HAMLIB_API amp_ext_parm_foreach(AMP *amp, int (*cfunc)(AMP *, @@ -142,15 +157,21 @@ int HAMLIB_API amp_ext_parm_foreach(AMP *amp, /** - * \param amp - * \param name - * \brief lookup ext token by its name, return pointer to confparams struct. + * \brief Lookup an extension levels or parameters token by its name and return + * a pointer to the containing #confparams structure member. * - * Lookup extlevels table first, then fall back to extparms. + * \param amp The #AMP handle. + * \param name The extension levels or parameters token name. * - * Returns NULL if nothing found + * Searches the amp_caps::extlevels table first and then falls back to + * amp_caps::extparms. * - * TODO: should use Lex to speed it up, strcmp hurts! + * \return A pointer to the containing #confparams structure member or NULL if + * nothing found or if \a amp is NULL or invalid. + * + * \sa amp_ext_token_lookup() + * + * TODO: should use Lex to speed it up, strcmp() hurts! */ const struct confparams *HAMLIB_API amp_ext_lookup(AMP *amp, const char *name) { @@ -184,13 +205,16 @@ const struct confparams *HAMLIB_API amp_ext_lookup(AMP *amp, const char *name) /** - * \param amp - * \param token - * \brief lookup ext token, return pointer to confparams struct. + * \brief Lookup an extension levels or parameters token by its constant value + * and return a pointer to the #confparams structure member. * - * lookup extlevels table first, then fall back to extparms. + * \param amp The #AMP handle. + * \param token The token value (constant). * - * Returns NULL if nothing found + * Searches the amp_caps::extlevels table first and then falls back to amp_caps::extparms. + * + * \return A pointer to the containing #confparams structure member or NULL if + * nothing found or if \a amp is NULL or invalid. */ const struct confparams *HAMLIB_API amp_ext_lookup_tok(AMP *amp, token_t token) { @@ -224,9 +248,15 @@ const struct confparams *HAMLIB_API amp_ext_lookup_tok(AMP *amp, token_t token) /** - * \param amp - * \param name - * \brief Simple lookup returning token id assicated with name + * \brief Simple lookup returning the extension token ID associated with \a + * name. + * + * \param amp The #AMP handle. + * \param name The name string to search. + * + * \return The token ID or RIG_CONF_END if there is a lookup failure. + * + * \sa amp_ext_lookup() */ token_t HAMLIB_API amp_ext_token_lookup(AMP *amp, const char *name) {