[Hamlib-commits] Hamlib -- Ham radio control libraries branch master updated. 7c26d2afef71d079b1bcd
Library to control radio transceivers and receivers
Brought to you by:
n0nb
Menu
▾
▴
[Hamlib-commits] Hamlib -- Ham radio control libraries branch master updated. 7c26d2afef71d079b1bcde62bf0ae66b4b181eb0
|
From: Nate B. <n0...@us...> - 2021-02-15 21:44:04
|
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "Hamlib -- Ham radio control libraries".
The branch, master has been updated
via 7c26d2afef71d079b1bcde62bf0ae66b4b181eb0 (commit)
via 2556f4fcd1a8caad33fcd46d5a58b6af47810edc (commit)
via 9dce43fc507bc7677849a5180d3ad9f7a3e24402 (commit)
from e016025c04f66b75c7773fc747dc8fe57e7565b1 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 7c26d2afef71d079b1bcde62bf0ae66b4b181eb0
Merge: e016025c 2556f4fc
Author: Nate Bargmann <n0...@n0...>
Date: Mon Feb 15 15:41:11 2021 -0600
Merge pull request #548 from N0NB/doxygen_work
Doxygen work
commit 2556f4fcd1a8caad33fcd46d5a58b6af47810edc
Author: Nate Bargmann <n0...@n0...>
Date: Mon Feb 15 15:38:20 2021 -0600
Udate amplifier documentation for consistency
diff --git a/src/amp_conf.c b/src/amp_conf.c
index 1e1390e4..bc0b4bd3 100644
--- a/src/amp_conf.c
+++ b/src/amp_conf.c
@@ -502,8 +502,8 @@ int HAMLIB_API amp_token_foreach(AMP *amp,
* to the frontend config params table.
*
* \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?).
+ * \a amp is NULL or inconsistent or if \a token is not found (how can the
+ * caller know which occurred?).
*
* \sa amp_token_lookup()
*
@@ -600,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 \a amp or \a token was invalid.
+ * \retval RIG_EINVAL \a amp is NULL or inconsistent or \a token is invalid.
* \retval RIG_ENAVAIL amp_caps#set_conf() capability is not available.
*
* \sa amp_get_conf()
@@ -656,7 +656,7 @@ int HAMLIB_API amp_set_conf(AMP *amp, token_t token, const char *val)
* value** if an error occurred (in which case, cause is set appropriately).
*
* \retval RIG_OK Querying the parameter was successful.
- * \retval RIG_EINVAL \a amp is NULL or invalid.
+ * \retval RIG_EINVAL \a amp is NULL or inconsistent.
* \retval RIG_ENAVAIL amp_caps#get_conf() capability is not available.
*
* \sa amp_set_conf()
diff --git a/src/amplifier.c b/src/amplifier.c
index 7d6d711e..9aa5056e 100644
--- a/src/amplifier.c
+++ b/src/amplifier.c
@@ -671,7 +671,7 @@ 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
- * \a amp is NULL or invalid or the amp_caps#get_info() capability is not
+ * \a amp is NULL or inconsistent or the amp_caps#get_info() capability is not
* available.
*/
const char *HAMLIB_API amp_get_info(AMP *amp)
diff --git a/src/extamp.c b/src/extamp.c
index 300e3429..a0dbd797 100644
--- a/src/extamp.c
+++ b/src/extamp.c
@@ -167,7 +167,7 @@ int HAMLIB_API amp_ext_parm_foreach(AMP *amp,
* 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.
+ * nothing found or if \a amp is NULL or inconsistent.
*
* \sa amp_ext_token_lookup()
*
@@ -214,7 +214,7 @@ const struct confparams *HAMLIB_API amp_ext_lookup(AMP *amp, const char *name)
* 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.
+ * nothing found or if \a amp is NULL or inconsistent.
*/
const struct confparams *HAMLIB_API amp_ext_lookup_tok(AMP *amp, token_t token)
{
commit 9dce43fc507bc7677849a5180d3ad9f7a3e24402
Author: Nate Bargmann <n0...@n0...>
Date: Mon Feb 15 15:36:47 2021 -0600
Update Docygen comments in rotator.c
Create new group for rot_internal that Doxygen shows under the Modules
tab.
diff --git a/doc/index.doxygen b/doc/index.doxygen
index 34c9c69c..22670887 100644
--- a/doc/index.doxygen
+++ b/doc/index.doxygen
@@ -102,8 +102,9 @@ Windows 32 bit on Debian GNU/Linux.
/*! Define groups for Doxygen
* \defgroup rig Rig (transceiver) API
+ * \defgroup rig_internal Rig (transceiver) Internal API
* \defgroup rotator Rotator API
- * \defgroup utilities Utility Routines API
- * \defgroup rig_internal Rig Internal API
+ * \defgroup rot_internal Rotator Internal API
* \defgroup amplifier Amplifier API
+ * \defgroup utilities Utility Routines API
*/
diff --git a/src/rotator.c b/src/rotator.c
index 8cb36a7e..159b85c7 100644
--- a/src/rotator.c
+++ b/src/rotator.c
@@ -28,18 +28,22 @@
/**
* \file src/rotator.c
* \brief Rotator interface
+ * \author Frank Singleton
+ * \date 2000-2003
* \author Stephane Fillod
* \date 2000-2012
*
- * Hamlib interface is a frontend implementing rotator wrapper functions.
+ * This Hamlib interface is a frontend implementing the rotator wrapper
+ * functions.
*/
/**
* \page rot Rotator interface
*
- * Rotator can be any kind of azimuth or azimuth and elevation controlled
- * antenna system.
+ * A rotator can be any kind of azimuth, elevation, or azimuth and elevation
+ * controlled antenna system or other such aiming equipment, e.g. telescopes,
+ * etc.
*/
#ifdef HAVE_CONFIG_H
@@ -147,22 +151,30 @@ static int remove_opened_rot(ROT *rot)
}
#endif /* !DOC_HIDDEN */
+/** @} */ /* rotator definitions */
+
/**
- * \brief execs cfunc() on each opened rot
- * \param cfunc The function to be executed on each rot
- * \param data Data pointer to be passed to cfunc()
+ * \addtogroup rot_internal
+ * @{
+ */
+
+
+/**
+ * \brief Executes \a cfunc on each opened #ROT.
+ *
+ * \param cfunc The function to be executed on each #ROT.
+ * \param data Data pointer to be passed to \a cfunc.
*
- * Calls cfunc() function for each opened rot. The contents of the opened
- * rot 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
- * #ROT handle, the second to a data pointer \a data.
+ * Calls \a cfunc function for each opened #ROT. The contents of the opened
+ * #ROT 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
+ * #ROT 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 rot table is stopped when cfunc() returns 0.
- * \internal
+ * If \a data is not needed, then it can be set to NULL. The processing of
+ * the opened #ROT table is stopped when \a cfunc returns 0.
*
- * \return always RIG_OK.
+ * \return RIG_OK in all cases.
*/
int foreach_opened_rot(int (*cfunc)(ROT *, rig_ptr_t), rig_ptr_t data)
{
@@ -180,17 +192,24 @@ int foreach_opened_rot(int (*cfunc)(ROT *, rig_ptr_t), rig_ptr_t data)
return RIG_OK;
}
+/** @} */ /* rot_internal definitions */
/**
- * \brief allocate a new #ROT handle
- * \param rot_model The rot model for this new handle
+ * \addtogroup rotator
+ * @{
+ */
+
+/**
+ * \brief Allocate a new #ROT handle.
+ *
+ * \param rot_model The rotator model for this new handle.
*
* Allocates a new #ROT handle and initializes the associated data
- * for \a rot_model.
+ * for \a rot_model (see rotlist.h or `rigctl -l`).
*
* \return a pointer to the #ROT handle otherwise NULL if memory allocation
- * failed or \a rot_model is unknown (e.g. backend autoload failed).
+ * failed or \a rot_model is unknown, e.g. backend autoload failed.
*
* \sa rot_cleanup(), rot_open()
*/
@@ -313,18 +332,19 @@ ROT *HAMLIB_API rot_init(rot_model_t rot_model)
/**
- * \brief open the communication to the rot
- * \param rot The #ROT handle of the rotator to be opened
+ * \brief Open the communication channel to the rotator.
*
- * Opens communication to a rotator which \a ROT handle has been passed
- * by argument.
+ * \param rot The #ROT handle of the rotator to be opened.
*
- * \return RIG_OK if the operation has been successful, otherwise
- * a negative value if an error occurred (in which case, cause is
- * set appropriately).
+ * Opens the communication channel to a rotator for which the #ROT handle has
+ * been passed.
*
- * \retval RIG_EINVAL \a rot is NULL or inconsistent.
- * \retval RIG_ENIMPL port type communication is not implemented yet.
+ * \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 Communication channel succesfully opened.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENIMPL Communication port type is not implemented yet.
*
* \sa rot_init(), rot_close()
*/
@@ -448,15 +468,17 @@ int HAMLIB_API rot_open(ROT *rot)
/**
- * \brief close the communication to the rot
- * \param rot The #ROT handle of the rotator to be closed
+ * \brief Close the communication channel to the rotator.
+ * \param rot The #ROT handle of the rotator to be closed.
+ *
+ * Closes the communication channel to a rotator for which #ROT handle has
+ * been passed by argument that was previously opened with rot_open().
*
- * Closes communication to a rotator which \a ROT handle has been passed
- * by argument that was previously open with rot_open().
+ * \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 Communication channel successfully closed.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
*
* \sa rot_cleanup(), rot_open()
*/
@@ -527,15 +549,18 @@ int HAMLIB_API rot_close(ROT *rot)
/**
- * \brief release a rot handle and free associated memory
- * \param rot The #ROT handle of the radio to be closed
+ * \brief Release a #ROT handle and free associated memory.
*
- * Releases a rot struct which port has eventually been closed already
+ * \param rot The #ROT handle to be released.
+ *
+ * Releases a #ROT handle for which the communication channel has been closed
* with rot_close().
*
- * \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 #ROT handle successfully released.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
*
* \sa rot_init(), rot_close()
*/
@@ -571,16 +596,25 @@ int HAMLIB_API rot_cleanup(ROT *rot)
/**
- * \brief set the azimuth and elevation of the rotator
- * \param rot The rot handle
- * \param azimuth The azimuth to set to
- * \param elevation The elevation to set to
+ * \brief Set the azimuth and elevation of the rotator.
+ *
+ * \param rot The #ROT handle.
+ * \param azimuth The azimuth to set in decimal degress.
+ * \param elevation The elevation to set in decimal degrees.
*
* Sets the azimuth and elevation of the rotator.
*
- * \return RIG_OK if the operation has been successful, otherwise
- * a negative value if an error occurred (in which case, cause is
- * set appropriately).
+ * \b Note: A given rotator may be capable of setting only the azimuth or
+ * only the elevation or both. The rotator backend will ignore the unneeded
+ * parameter.
+ *
+ * \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 Either or both parameters set successfully.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent \b or either \a azimuth
+ * or \a elevation is out of range for this rotator.
+ * \retval RIG_ENAVAIL rot_caps#set_position() capability is not available.
*
* \sa rot_get_position()
*/
@@ -634,16 +668,25 @@ int HAMLIB_API rot_set_position(ROT *rot,
/**
- * \brief get the azimuth and elevation of the rotator
- * \param rot The rot handle
- * \param azimuth The location where to store the current azimuth
- * \param elevation The location where to store the current elevation
+ * \brief Query the azimuth and elevation of the rotator.
+ *
+ * \param rot The #ROT handle.
+ * \param azimuth The variable to store the current azimuth.
+ * \param elevation The variable to store the current elevation
+ *
+ * Retrieves the current azimuth and elevation values of the rotator. The
+ * stored values are in decimal degrees.
*
- * Retrieves the current azimuth and elevation of the rotator.
+ * \b Note: A given rotator may be capable of querying only the azimuth or
+ * only the elevation or both. The rotator backend should store a value of 0
+ * in the unsupported variable.
*
- * \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 Either or both parameters queried and stored successfully.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENAVAIL rot_caps#get_position() capability is not available.
*
* \sa rot_set_position()
*/
@@ -692,14 +735,19 @@ int HAMLIB_API rot_get_position(ROT *rot,
/**
- * \brief park the antenna
- * \param rot The rot handle
+ * \brief Park the rotator.
+ *
+ * \param rot The #ROT handle.
*
- * Park the antenna.
+ * Park the rotator in a predetermined position as implemented by the rotator
+ * hardware.
*
- * \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 rotator was parked successfully.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENAVAIL rot_caps#park() capability is not available.
*
*/
int HAMLIB_API rot_park(ROT *rot)
@@ -725,15 +773,20 @@ int HAMLIB_API rot_park(ROT *rot)
/**
- * \brief stop the rotator
- * \param rot The rot handle
+ * \brief Stop the rotator.
+ *
+ * \param rot The #ROT handle.
*
- * Stop the rotator.
+ * Stop the rotator. Command should be immediate.
*
- * \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 rotator was stopped successfully.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENAVAIL rot_caps#stop() capability is not available.
+ *
+ * \sa rot_move()
*/
int HAMLIB_API rot_stop(ROT *rot)
{
@@ -758,16 +811,19 @@ int HAMLIB_API rot_stop(ROT *rot)
/**
- * \brief reset the rotator
- * \param rot The rot handle
+ * \brief Reset the rotator.
+ *
+ * \param rot The #ROT handle.
* \param reset The reset operation to perform
*
- * Resets the rotator.
+ * Resets the rotator to a state determined by \a reset.
*
- * \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 rotator was reset successfully.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENAVAIL rot_caps#reset() capability is not available.
*/
int HAMLIB_API rot_reset(ROT *rot, rot_reset_t reset)
{
@@ -792,13 +848,22 @@ int HAMLIB_API rot_reset(ROT *rot, rot_reset_t reset)
/**
- * \brief move the rotator in the specified direction
- * \param rot The rot handle
- * \param direction Direction of movement
- * \param speed Speed of movement
+ * \brief Move the rotator in the specified direction and speed.
+ *
+ * \param rot The #ROT handle.
+ * \param direction Direction of movement.
+ * \param speed Speed of movement.
+ *
+ * Move the rotator in the specified direction. The \a direction is one of
+ * #ROT_MOVE_CCW, #ROT_MOVE_CW, #ROT_MOVE_LEFT, #ROT_MOVE_RIGHT, #ROT_MOVE_UP,
+ * or #ROT_MOVE_DOWN. The \a speed is a value between 1 and 100 or
+ * #ROT_SPEED_NOCHANGE.
*
- * Move the rotator in the specified direction. The speed is a value
- * between 1 and 100.
+ * \retval RIG_OK The rotator move was successful.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENAVAIL rot_caps#move() capability is not available.
+ *
+ * \sa rot_stop()
*/
int HAMLIB_API rot_move(ROT *rot, int direction, int speed)
{
@@ -823,15 +888,17 @@ int HAMLIB_API rot_move(ROT *rot, int direction, int speed)
/**
- * \brief get general information from the rotator
- * \param rot The rot handle
+ * \brief Get general information from the rotator.
+ *
+ * \param rot The #ROT handle.
*
- * Retrieves some general information from the rotator.
- * This can include firmware revision, exact model name, or just nothing.
+ * Retrieves some general information from the rotator. This can include
+ * firmware revision, exact model name, or just nothing.
*
- * \return a pointer to static memory containing the ASCIIZ string
- * if the operation has been successful, otherwise NULL if an error occurred
- * or get_info not part of capabilities.
+ * \return A pointer to static memory containing an ASCII nul terminated
+ * string (C string) if the operation has been successful, otherwise NULL if
+ * \a rot is NULL or inconsisten or the rot_caps#get_info() capability is not
+ * available.
*/
const char *HAMLIB_API rot_get_info(ROT *rot)
{
@@ -852,15 +919,19 @@ const char *HAMLIB_API rot_get_info(ROT *rot)
/**
- * \brief get status flags from the rotator
- * \param rot The rot handle
- * \param status a pointer to a rot_status_t variable that will receive the status flags
+ * \brief Query status flags of the rotator.
+ *
+ * \param rot The #ROT handle.
+ * \param status The variable where the status flags will be stored.
+ *
+ * Query the active status flags from the rotator.
*
- * Gets the active status flags from the rotator.
+ * \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 query was successful.
+ * \retval RIG_EINVAL \a rot is NULL or inconsistent.
+ * \retval RIG_ENAVAIL rot_caps#get_status() capability is not available.
*/
int HAMLIB_API rot_get_status(ROT *rot, rot_status_t *status)
{
-----------------------------------------------------------------------
Summary of changes:
doc/index.doxygen | 5 +-
src/amp_conf.c | 8 +-
src/amplifier.c | 2 +-
src/extamp.c | 4 +-
src/rotator.c | 257 ++++++++++++++++++++++++++++++++++--------------------
5 files changed, 174 insertions(+), 102 deletions(-)
hooks/post-receive
--
Hamlib -- Ham radio control libraries
|
