mirror
/
Hamlib
kopia lustrzana https://github.com/Hamlib/Hamlib
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Update Doxygen comments for amplifier group 

Aim for consistency in Doxygen comments structure.
pull/545/head
Nate Bargmann 2021-02-12 12:46:01 -06:00
rodzic 64b0b37d49
commit 2bf4a49f5d
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: F72625E2EDBED598
6 zmienionych plików z 177 dodań i 111 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

28
include/hamlib/amplifier.h
Wyświetl plik

@ -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
* <a href="https://en.wikipedia.org/wiki/Standing_wave_ratio" >SWR (Standing Wave Ratio)</a>.
*
* \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
* <a href="http://www.arrl.org/transmatch-antenna-tuner" >transmatch</a>
* tuning values of
@ -86,6 +88,8 @@ typedef float swr_t;
* and
* <a href="https://en.wikipedia.org/wiki/Inductance" >inductance</a>.
*
* \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.
*/

62
include/hamlib/amplist.h
Wyświetl plik

@ -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;

32
src/amp_conf.c
Wyświetl plik

@ -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()

7
src/amp_settings.c
Wyświetl plik

@ -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.
*

59
src/amplifier.c
Wyświetl plik

@ -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.
*

100
src/extamp.c
Wyświetl plik

@ -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)
{