diff --git a/doc/Makefile.am b/doc/Makefile.am index 79cdfe159..bcb3e2aff 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -5,9 +5,41 @@ dist_man_MANS = man1/ampctl.1 man1/ampctld.1 \ man1/rigswr.1 man1/rotctl.1 man1/rotctld.1 man1/rigctlcom.1 \ man7/hamlib.7 man7/hamlib-primer.7 man7/hamlib-utilities.7 -SRCDOCLST = ../src/rig.c ../src/rotator.c ../src/tones.c ../src/locator.c \ - ../src/event.c ../src/conf.c ../src/mem.c ../src/settings.c +SRCDOCLST = \ + ../include/hamlib/amplifier.h \ + ../include/hamlib/amplist.h \ + ../include/hamlib/rig.h \ + ../include/hamlib/rotator.h \ + ../include/hamlib/rotlist.h \ + ../src/amp_conf.c \ + ../src/amp_settings.c \ + ../src/amplifier.c \ + ../src/cal.c \ + ../src/cm108.c \ + ../src/conf.c \ + ../src/debug.c \ + ../src/event.c \ + ../src/ext.c \ + ../src/extamp.c \ + ../src/locator.c \ + ../src/mem.c \ + ../src/misc.c \ + ../src/network.c \ + ../src/parallel.c \ + ../src/rig.c \ + ../src/rot_conf.c \ + ../src/rot_ext.c \ + ../src/rot_settings.c \ + ../src/rotator.c \ + ../src/tones.c \ + ../src/serial.c \ + ../src/settings.c \ + ../src/sleep.c \ + ../src/token.h \ + ../src/tones.c \ + ../src/usb_port.c +# Just the file names, the paths are assigned below. SCRIPTSLST = build-w32.sh build-w64.sh diff --git a/src/cal.c b/src/cal.c index f9ba69121..8abd75a7a 100644 --- a/src/cal.c +++ b/src/cal.c @@ -27,7 +27,7 @@ /** * \file cal.c - * \brief Calibration routines + * \brief Calibration routines. */ #ifdef HAVE_CONFIG_H @@ -41,17 +41,24 @@ /** - * \brief Convert raw data to a calibrated integer value, according to table - * \param rawval input value - * \param cal calibration table - * \return calibrated integer value - - * cal_table_t is a data type suited to hold linear calibration - * cal_table_t.size tell the number of plot cal_table_t.table contains + * \brief Convert raw data to a calibrated integer value, according to a + * calibration table. + * + * \param rawval Input value. + * \param cal Calibration table, + * + * cal_table_t is a data type suited to hold linear calibration. + * + * cal_table_t.size is the number of plots cal_table_t.table contains. + * * If a value is below or equal to cal_table_t.table[0].raw, - * rig_raw2val() will return cal_table_t.table[0].val - * If a value is greater or equal to cal_table_t.table[cal_table_t.size-1].raw, - * rig_raw2val() will return cal_table_t.table[cal_table_t.size-1].val + * rig_raw2val() will return cal_table_t.table[0].val. + * + * If a value is greater or equal to + * cal_table_t.table[cal_table_t.size-1].raw, rig_raw2val() will return + * cal_table_t.table[cal_table_t.size-1].val. + * + * \return Calibrated integer value. */ float HAMLIB_API rig_raw2val(int rawval, const cal_table_t *cal) { @@ -111,18 +118,26 @@ float HAMLIB_API rig_raw2val(int rawval, const cal_table_t *cal) return cal->table[i].val - interpolation; } -/** - * \brief Convert raw data to a calibrated floating-point value, according to table - * \param rawval input value - * \param cal calibration table - * \return calibrated floating-point value - * cal_table_float_t is a data type suited to hold linear calibration - * cal_table_float_t.size tell the number of plot cal_table_t.table contains +/** + * \brief Convert raw data to a calibrated floating-point value, according to + * a calibration table. + * + * \param rawval Input value. + * \param cal Calibration table. + * + * cal_table_float_t is a data type suited to hold linear calibration. + * + * cal_table_float_t.size tell the number of plot cal_table_t.table contains. + * * If a value is below or equal to cal_table_float_t.table[0].raw, - * rig_raw2val_float() will return cal_table_float_t.table[0].val - * If a value is greater or equal to cal_table_float_t.table[cal_table_float_t.size-1].raw, - * rig_raw2val_float() will return cal_table_float_t.table[cal_table_float_t.size-1].val + * rig_raw2val_float() will return cal_table_float_t.table[0].val. + * + * If a value is greater or equal to + * cal_table_float_t.table[cal_table_float_t.size-1].raw, rig_raw2val_float() + * will return cal_table_float_t.table[cal_table_float_t.size-1].val. + * + * \return calibrated floating-point value */ float HAMLIB_API rig_raw2val_float(int rawval, const cal_table_float_t *cal) { diff --git a/src/cm108.c b/src/cm108.c index 2de83c94f..9c942edfd 100644 --- a/src/cm108.c +++ b/src/cm108.c @@ -26,8 +26,11 @@ */ /** - * \brief CM108 GPIO * \file cm108.c + * \brief CM108 GPIO support. + * + * CM108 Audio chips found on many USB audio interfaces have controllable + * General Purpose Input/Output pins. */ #ifdef HAVE_CONFIG_H # include "config.h" @@ -73,9 +76,15 @@ /** - * \brief Open CM108 HID port (/dev/hidrawX) - * \param port - * \return file descriptor + * \brief Open CM108 HID port (/dev/hidrawX). + * + * \param port The port structure. + * + * \return File descriptor, otherwise a **negative value** if an error + * occurred (in which case, cause is set appropriately). + * + * \retval RIG_EINVAL The port pathname is empty or no CM108 device detected. + * \retval RIG_EIO The `open`(2) system call returned a **negative value**. */ int cm108_open(hamlib_port_t *port) { @@ -144,8 +153,14 @@ int cm108_open(hamlib_port_t *port) /** - * \brief Close CM108 HID port - * \param port + * \brief Close a CM108 HID port. + * + * \param port The port structure + * + * \return Zero if the port was closed successfully, otherwise -1 if an error + * occurred (in which case, the system `errno`(3) is set appropriately). + * + * \sa The `close`(2) system call. */ int cm108_close(hamlib_port_t *port) { @@ -156,10 +171,18 @@ int cm108_close(hamlib_port_t *port) /** - * \brief Set or unset Push to talk bit on CM108 GPIO - * \param p - * \param pttx RIG_PTT_ON --> Set PTT - * \return RIG_OK or < 0 error + * \brief Set or unset the Push To Talk bit on a CM108 GPIO. + * + * \param p The port structure. + * \param pttx RIG_PTT_ON --> Set PTT, else unset PTT. + * + * \return RIG_OK on success, otherwise a **negative value** if an error + * occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK Setting or unsetting the PTT was successful. + * \retval RIG_EINVAL The file descriptor is invalid or the PTT type is + * unsupported. + * \retval RIG_EIO The `write`(2) system call returned a **negative value**. */ int cm108_ptt_set(hamlib_port_t *p, ptt_t pttx) { @@ -232,10 +255,17 @@ int cm108_ptt_set(hamlib_port_t *p, ptt_t pttx) /** - * \brief Get state of Push to Talk from CM108 GPIO - * \param p - * \param pttx return value (must be non NULL) - * \return RIG_OK or < 0 error + * \brief Get the state of Push To Talk from a CM108 GPIO. + * + * \param p The port structure. + * \param pttx Return value (must be non NULL). + * + * \return RIG_OK on success, otherwise a **negative value** if an error + * occurred (in which case, cause is set appropriately). + * + * \retval RIG_OK Getting the PTT state was successful. + * \retval RIG_ENIMPL Getting the state is not yet implemented. + * \retval RIG_ENAVAIL Getting the state is not available for this PTT type. */ int cm108_ptt_get(hamlib_port_t *p, ptt_t *pttx) { @@ -259,6 +289,7 @@ int cm108_ptt_get(hamlib_port_t *p, ptt_t *pttx) return RIG_OK; } + #ifdef XXREMOVEXX // Not referenced anywhere /**