documentation

git-svn-id: https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk@2145 7ae35d74-ebe9-4afe-98af-79ac388436b8

doc/hamlib.cfg.in

@@ -1,6 +1,6 @@
-## $Id: hamlib.cfg.in,v 1.3 2006-10-13 18:24:02 aa6e Exp $
+## $Id: hamlib.cfg.in,v 1.4 2006-10-15 00:24:27 aa6e Exp $
 
-PROJECT_NAME    = "Hamlib - the C library reference"
+PROJECT_NAME    = "Hamlib"
 PROJECT_NUMBER  = @VERSION@
 
 # Output
@@ -28,7 +28,8 @@ INPUT	= @top_srcdir@/doc/index.doxygen \
 	  @top_srcdir@/include/hamlib/rig.h \
           @top_srcdir@/include/hamlib/riglist.h \
 	  @top_srcdir@/include/hamlib/rotator.h \
-          @top_srcdir@/include/hamlib/rotlist.h
+          @top_srcdir@/include/hamlib/rotlist.h \
+    @top_srcdir@/src/cal.c
 
 #../c++/rigclass.cc
 

doc/hamlib.css

@@ -2,18 +2,18 @@ BODY { font-size: 0.80em; width: 700px; }
 H1 { text-align: center; }
 A.qindex {}
 A.qindexRef {}
-A.el { font-size: 1.00em; text-decoration: none; font-weight: bold; font-family: courier,helvetica,serif }
+A.el { font-size: 1.20em; text-decoration: none; font-weight: bold; font-family: courier,helvetica,serif }
-A.elRef { font-size: 1.00em; font-weight: bold; font-family: courier,helvetica,serif }
+A.elRef { font-size: 1.20em; font-weight: bold; font-family: courier,helvetica,serif }
-A.code { font-size: 1.00em; text-decoration: none; font-weight: normal; color: #4444ee; font-family: courier,helvetica,serif }
+A.code { font-size: 1.20em; text-decoration: none; font-weight: normal; color: #4444ee; font-family: courier,helvetica,serif }
-A.codeRef { font-size: 1.00em;font-weight: normal; color: #4444ee; font-family: courier,helvetica,serif }
+A.codeRef { font-size: 1.20em;font-weight: normal; color: #4444ee; font-family: courier,helvetica,serif }
 A:hover { text-decoration: none; background-color: #f0f0fd; }
 DL.el { margin-left: -1cm }
 DIV.fragment { width: 100%; border: none; background-color: #eeeeee; font-family: courier,helvetica,serif }
-DIV.ah { font-size: 1.00em; background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px; font-family: courier,helvetica,serif }
+DIV.ah { font-size: 1.20em; background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px; font-family: courier,helvetica,serif }
-TD.md { font-size: 1.00em; background-color: #f2f2ff; font-weight: bold; font-family: courier,helvetica,serif }
+TD.md { font-size: 1.20em; background-color: #f2f2ff; font-weight: bold; font-family: courier,helvetica,serif }
-TD.mdname { font-size: 1.00em; background-color: #f2f2ff; font-weight: bold; font-style: italic; font-family: courier,helvetica,serif }
+TD.mdname { font-size: 1.20em; background-color: #f2f2ff; font-weight: bold; font-style: italic; font-family: courier,helvetica,serif }
 DIV.groupHeader { margin-left: 16px; margin-top: 12px; margin-bottom: 6px; font-weight: bold; font-family: courier,helvetica,serif }
-DIV.groupText { margin-left: 16px; font-style: italic; font-size: 1.00em; font-family: courier,helvetica,serif }
+DIV.groupText { margin-left: 16px; font-style: italic; font-size: 1.20em; font-family: courier,helvetica,serif }
 FONT.keyword       { color: #008000 }
 FONT.keywordtype   { color: #604020 }
 FONT.keywordflow   { color: #e08000 }

doc/index.doxygen

@@ -100,3 +100,10 @@ of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 /*! \page TODO TO DO
 \verbinclude TODO
 */
+
+/*! Define groups for Doxygen
+ *  \defgroup rig Rig (transceiver) API
+ *  \defgroup rotator Rotator API
+ *  \defgroup utilities Utility Routines API
+ *  \defgroup rig_internal Rig Internal API
+ */

include/hamlib/rig.h

@@ -2,7 +2,7 @@
  *  Hamlib Interface - API header
  *  Copyright (c) 2000-2005 by Stephane Fillod and Frank Singleton
  *
- *	$Id: rig.h,v 1.115 2006-10-12 16:41:22 aa6e Exp $
+ *	$Id: rig.h,v 1.116 2006-10-15 00:26:47 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,7 @@
  *
  */
 
+
 #ifndef _RIG_H
 #define _RIG_H 1
 
@@ -28,8 +29,12 @@
 
 #include <hamlib/riglist.h>	/* list in another file to not mess up w/ this one */
 
+/**
+ * \addtogroup rig
+ * @{
+ */
+
 /*! \file rig.h
- *  \ingroup rig
  *  \brief Hamlib rig data structures.
  *
  *  This file contains the data structures and definitions for the Hamlib rig API.
@@ -1624,3 +1629,5 @@ extern HAMLIB_EXPORT(rptr_shift_t) rig_parse_rptr_shift(const char *s);
 __END_DECLS
 
 #endif /* _RIG_H */
+
+/*! @} */

include/hamlib/rotator.h

@@ -2,7 +2,7 @@
  *  Hamlib Interface - Rotator API header
  *  Copyright (c) 2000-2005 by Stephane Fillod
  *
- *	$Id: rotator.h,v 1.13 2005-04-03 12:27:15 fillods Exp $
+ *	$Id: rotator.h,v 1.14 2006-10-15 00:26:47 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -26,9 +26,12 @@
 #include <hamlib/rig.h>
 #include <hamlib/rotlist.h>
 
+/**
+ * \addtogroup rotator
+ * @{
+ */
 
 /*! \file rotator.h
- *  \ingroup rot
  *  \brief Hamlib rotator data structures.
  *
  *  This file contains the data structures and definitions for the Hamlib rotator API.
@@ -363,3 +366,4 @@ __END_DECLS
 
 #endif /* _ROTATOR_H */
 
+/** @} */

include/hamlib/rotlist.h

@@ -2,7 +2,7 @@
  *  Hamlib Interface - list of known rotators
  *  Copyright (c) 2000-2002 by Stephane Fillod and Frank Singleton
  *
- *	$Id: rotlist.h,v 1.9 2003-06-22 19:38:26 fillods Exp $
+ *	$Id: rotlist.h,v 1.10 2006-10-15 00:26:47 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -26,8 +26,12 @@
 #define ROT_MAKE_MODEL(a,b) ((a)*100+(b))
 #define ROT_BACKEND_NUM(a) ((a)/100)
 
+/**
+ * \addtogroup rotator
+ * @{
+ */
+
 /*! \file rotlist.h
- *  \ingroup rot
  *  \brief Hamlib rotator model definitions.
  *
  *  This file contains rotator model definitions for the Hamlib rotator API.
@@ -42,7 +46,6 @@
  *  use. It is done with the rot_init() API call.
  */
 
-
 #define ROT_MODEL_NONE 0
 
 /*! \def ROT_MODEL_DUMMY
@@ -71,7 +74,6 @@
 #define ROT_BACKEND_RPC "rpcrot"
 #define ROT_MODEL_RPC ROT_MAKE_MODEL(ROT_RPC, 1)
 
-
 	/*
 	 * Easycomm
 	 */
@@ -136,13 +138,11 @@
 #define ROT_BACKEND_SARTEK "sartek"
 #define ROT_MODEL_SARTEK1 ROT_MAKE_MODEL(ROT_SARTEK, 1)
 
-
 /*! \typedef typedef int rot_model_t
     \brief Convenience type definition for rotator model.
 */
 typedef int rot_model_t;
 
-
 /*! \def ROT_BACKEND_LIST
  *  \brief Static list of rotator models.
  *
@@ -169,3 +169,5 @@ typedef int rot_model_t;
  */
 
 #endif /* _ROTLIST_H */
+
+/** @} */

src/cal.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - calibration routines
  *  Copyright (c) 2000-2004 by Stephane Fillod and Frank Singleton
  *
- *		$Id: cal.c,v 1.5 2004-10-02 10:32:08 fillods Exp $
+ *		$Id: cal.c,v 1.6 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,16 @@
  *
  */
 
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
+/**
+ * \file cal.c
+ * \brief Calibration routines
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -29,7 +39,12 @@
 
 /* add rig_set_cal(cal_table), rig_get_calstat(rawmin,rawmax,cal_table), */
 
-/*
+/**
+ * \brief Convert raw S-meter data to calibated value, according to table
+ * \param rawval input value
+ * \param cal calibration table
+ * \return calibrated 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
  * If a value is below or equal to cal_table_t.table[0].raw, 
@@ -83,3 +98,4 @@ float HAMLIB_API rig_raw2val(int rawval, const cal_table_t *cal)
 	return cal->table[i].val - interpolation;
 }
 
+/** @} */

src/conf.c

@@ -1,6 +1,10 @@
+/**
+ * \addtogroup rig
+ * @{
+ */
+
 /**
  * \file src/conf.c
- * \ingroup rig
  * \brief Rig configuration interface
  * \author Stephane Fillod
  * \date 2000-2006
@@ -9,7 +13,7 @@
  *  Hamlib Interface - configuration interface
  *  Copyright (c) 2000-2006 by Stephane Fillod
  *
- *	$Id: conf.c,v 1.14 2006-02-26 19:29:19 fillods Exp $
+ *	$Id: conf.c,v 1.15 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -457,3 +461,4 @@ int HAMLIB_API rig_get_conf(RIG *rig, token_t token, char *val)
 	return rig->caps->get_conf(rig, token, val);
 }
 
+/*! @} */

src/debug.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - debug
  *  Copyright (c) 2000-2006 by Stephane Fillod
  *
- *	$Id: debug.c,v 1.3 2006-02-26 23:28:13 fillods Exp $
+ *	$Id: debug.c,v 1.4 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,16 @@
  *
  */
 
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
+/**
+ * \file debug.c
+ * \brief control hamlib debugging functions
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -43,12 +53,13 @@ static FILE *rig_debug_stream;
 static vprintf_cb_t rig_vprintf_cb;
 static rig_ptr_t rig_vprintf_arg;
 
-/*
- * Do a hex dump of the unsigned char array.
- */
 
 #define DUMP_HEX_WIDTH 16
-
+/**
+ * \param ptr Pointer to memory area
+ * \param size Number of chars to words to dump
+ * \brief Do a hex dump of the unsigned char array.
+ */
 void dump_hex(const unsigned char ptr[], size_t size)
 {
   int i;
@@ -89,27 +100,28 @@ void dump_hex(const unsigned char ptr[], size_t size)
 } 
 
 
-/*
+/**
- * rig_set_debug
+ * \param debug_level
- * Change the current debug level
+ * \brief Change the current debug level
  */
 void HAMLIB_API rig_set_debug(enum rig_debug_level_e debug_level)
 {
 	rig_debug_level = debug_level;
 }
 
-/*
+/**
- * rig_need_debug
+ * \param debug_level
- * Usefull for dump_hex, etc.
+ * \brief Useful for dump_hex, etc.
  */
 int HAMLIB_API rig_need_debug(enum rig_debug_level_e debug_level)
 {
 	return (debug_level <= rig_debug_level);
 }
 
-/*
+/**
- * rig_debug
+ * \param debug_level
- * Default is debugging messages are done through stderr
+ * \param fmt
+ * \brief Default is debugging messages are done through stderr
  */
 void HAMLIB_API rig_debug(enum rig_debug_level_e debug_level, const char *fmt, ...)
 {
@@ -193,3 +205,4 @@ FILE* HAMLIB_API rig_set_debug_file(FILE *stream)
 	return prev_stream;
 }
 
+/** @} */

src/event.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - event handling
  *  Copyright (c) 2000-2004 by Stephane Fillod and Frank Singleton
  *
- *	$Id: event.c,v 1.24 2004-10-02 10:32:08 fillods Exp $
+ *	$Id: event.c,v 1.25 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,17 @@
  *
  */
 
+/* Doc todo: Verify assignment to rig group.  Consider doc of internal rtns. */
+/**
+ * \addtogroup rig
+ * @{
+ */
+
+/**
+ * \file event.c
+ * \brief Event handling
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -639,4 +650,4 @@ int HAMLIB_API rig_get_trn(RIG *rig, int *trn)
 	return RIG_OK;
 }
 
-
+/** @} */

src/ext.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - extrq parameter interface
  *  Copyright (c) 2000-2004 by Stephane Fillod
  *
- *	$Id: ext.c,v 1.4 2006-09-22 19:55:59 n0nb Exp $
+ *	$Id: ext.c,v 1.5 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -19,6 +19,12 @@
  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  *
  */
+/**
+ * \file ext.c
+ * \brief Ext. request parameter interface
+ */
+
+/* doc todo: Are these in the Hamlib API? */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"

src/iofunc.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - generic file based io functions
  *  Copyright (c) 2000-2004 by Stephane Fillod and Frank Singleton
  *
- *	$Id: iofunc.c,v 1.15 2006-10-07 21:33:31 csete Exp $
+ *	$Id: iofunc.c,v 1.16 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -19,6 +19,17 @@
  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  *
  */
+
+/**
+ * \file iofunc.c
+ * \brief Generic file-based IO functions
+ */
+
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -44,8 +55,14 @@
 #define select win32_serial_select
 #endif
 
-/*
+/**
- * Write a block of count characters to file descriptor,
+ * \brief Write a block of characters to an fd.
+ * \param p rig port descriptor
+ * \param txbuffer command sequence to be sent
+ * \param count number of bytes to send
+ * \return 0 = OK, <0 = NOK
+ *
+ * Write a block of count characters to port file descriptor,
  * with a pause between each character if write_delay is > 0
  *
  * The write_delay is for Yaesu type rigs..require 5 character
@@ -54,8 +71,6 @@
  * Also, post_write_delay is for some Yaesu rigs (eg: FT747) that
  * get confused with sequential fast writes between cmd sequences.
  *
- *
- *
  * input:
  *
  * fd - file descriptor to write to
@@ -65,11 +80,6 @@
  * post_write_delay - minimum delay between two writes
  * post_write_date - timeval of last write
  *
- * returns:
- *
- *  0 = OK
- *  <0 = NOT OK
- *
  * Actually, this function has nothing specific to serial comm,
  * it could work very well also with any file handle, like a socket.
  */
@@ -134,7 +144,13 @@ int HAMLIB_API write_block(hamlib_port_t *p, const char *txbuffer, size_t count)
 }
 
 
-/*
+/**
+ * \brief Read bytes from an fd
+ * \param p rig port descriptor
+ * \param rxbuffer buffer to receive text
+ * \param count number of bytes
+ * \return count of bytes received
+ *
  * Read "num" bytes from "fd" and put results into
  * an array of unsigned char pointed to by "rxbuffer"
  * 
@@ -199,7 +215,14 @@ int HAMLIB_API read_block(hamlib_port_t *p, char *rxbuffer, size_t count)
 }
 
 
-/*
+/**
+ * \brief Read a string from an fd
+ * \param p Hamlib port descriptor
+ * \param rxbuffer buffer to receive string
+ * \param rxmax maximum string size + 1
+ * \param stopset string of recognized end of string characters
+ * \param stopset_len length of stopset
+ *
  * Read a string from "fd" and put result into
  * an array of unsigned char pointed to by "rxbuffer"
  *
@@ -276,3 +299,4 @@ int HAMLIB_API read_string(hamlib_port_t *p, char *rxbuffer, size_t rxmax, const
   return total_count;			/* return bytes count read */
 }
 
+/** @} */

src/locator.c

@@ -1,6 +1,10 @@
+/**
+ * \addtogroup utilities
+ * @{
+ */
+
 /**
  * \file src/locator.c
- * \ingroup hamlib
  * \brief locator and bearing conversion interface
  * \author Stephane Fillod and the Hamlib Group
  * \date 2000-2006
@@ -14,7 +18,7 @@
  *  Copyright (c) 2003 by Nate Bargmann
  *  Copyright (c) 2003 by Dave Hines
  *
- *	$Id: locator.c,v 1.18 2006-02-26 19:29:19 fillods Exp $
+ *	$Id: locator.c,v 1.19 2006-10-15 00:27:51 aa6e Exp $
  *
  *  Code to determine bearing and range was taken from the Great Circle,
  *  by S. R. Sampson, N5OWK.
@@ -592,3 +596,5 @@ double HAMLIB_API distance_long_path(double distance) {
 double HAMLIB_API azimuth_long_path(double azimuth) {
 	return 360.0 - azimuth;
 }
+
+/*! @} */

src/mem.c

@@ -1,18 +1,22 @@
+/** \addtogroup rig
+ * @{
+ */
+
 /**
  * \file src/mem.c
- * \ingroup rig
  * \brief Memory and channel interface
  * \author Stephane Fillod
  * \date 2000-2006
  *
  * Hamlib interface is a frontend implementing wrapper functions.
+ * 
  */
 
 /*
  *  Hamlib Interface - mem/channel calls
  *  Copyright (c) 2000-2006 by Stephane Fillod
  *
- *	$Id: mem.c,v 1.10 2006-10-12 18:56:48 aa6e Exp $
+ *	$Id: mem.c,v 1.11 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -995,3 +999,4 @@ int HAMLIB_API rig_get_mem_all (RIG *rig, channel_t chans[], const struct confpa
 	return retval;
 }
 
+/*! @} */

src/misc.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - toolbox
  *  Copyright (c) 2000-2005 by Stephane Fillod
  *
- *	$Id: misc.c,v 1.39 2006-07-18 22:51:43 n0nb Exp $
+ *	$Id: misc.c,v 1.40 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,16 @@
  *
  */
 
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
+/**
+ * \file misc.c
+ * \brief Miscellaneous utility routines
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -38,8 +48,13 @@
 
 #include "misc.h"
 
-
+/**
-/*
+ * \brief Convert from binary to 4-bit BCD digits, little-endian
+ * \param bcd_data
+ * \param freq
+ * \param bcd_len
+ * \return bcd_data
+ *
  * Convert a long long (eg. frequency in Hz) to 4-bit BCD digits, 
  * packed two digits per octet, in little-endian order.
  * bcd_len is the number of BCD digits, usually 10 or 8 in 1-Hz units, 
@@ -71,7 +86,12 @@ HAMLIB_API to_bcd(unsigned char bcd_data[], unsigned long long freq, unsigned bc
 	return bcd_data;
 }
 
-/*
+/**
+ * \brief Convert BCD digits to a long long (eg. frequency in Hz)
+ * \param bcd_data
+ * \param bcd_len
+ * \return binary result (e.g. frequency)
+ *
  * Convert BCD digits to a long long (eg. frequency in Hz)
  * bcd_len is the number of BCD digits.
  *
@@ -95,7 +115,13 @@ unsigned long long HAMLIB_API from_bcd(const unsigned char bcd_data[], unsigned
 	return f;
 }
 
-/*
+/**
+ * \brief Convert binary to bcd, big-endian
+ * \param bcd_data
+ * \param freq
+ * \param bcd_len
+ * \return bcd_data
+ *
  * Same as to_bcd, but in Big Endian mode
  */
 unsigned char *
@@ -123,7 +149,12 @@ HAMLIB_API to_bcd_be(unsigned char bcd_data[], unsigned long long freq, unsigned
 	return bcd_data;
 }
 
-/*
+/**
+ * \brief Convert bcd to binary, big-endian
+ * \param bcd_data
+ * \param bcd_len
+ * \return binary value, e.g., frequency
+ *
  * Same as from_bcd, but in Big Endian mode
  */
 unsigned long long HAMLIB_API from_bcd_be(const unsigned char bcd_data[], unsigned bcd_len)
@@ -150,7 +181,11 @@ unsigned long long HAMLIB_API from_bcd_be(const unsigned char bcd_data[], unsign
 #define llabs(a) ((a)<0?-(a):(a))
 #endif
 
-/*
+/**
+ * \brief Pretty print a frequency
+ * \param str for result (may need up to 17 char)
+ * \param freq input in Hz
+ *
  * rig_freq_snprintf?
  * pretty print frequencies
  * str must be long enough. max can be as long as 17 chars
@@ -177,17 +212,11 @@ int HAMLIB_API sprintf_freq(char *str, freq_t freq)
 	return sprintf (str, "%g %s", f, hz);
 }
 
-const char * HAMLIB_API rig_strptrshift(rptr_shift_t shift)
+/**
-{
+ * \brief Convert enum RIG_STATUS_... to printable string
-	switch (shift) {
+ * \param status RIG_STATUS_??
-	case RIG_RPT_SHIFT_MINUS: return "+";
+ * \return string
-	case RIG_RPT_SHIFT_PLUS: return "-";
+ */
-
-	case RIG_RPT_SHIFT_NONE: return "None";
-	}
-	return NULL;
-}
-
 const char * HAMLIB_API rig_strstatus(enum rig_status_e status)
 {
 	switch (status) {
@@ -231,7 +260,11 @@ static struct {
 	{ RIG_MODE_NONE, "" },
 };
 
-
+/**
+ * \brief Convert alpha string to enum RIG_MODE
+ * \param s input alpha string
+ * \return enum RIG_MODE_??
+ */
 rmode_t HAMLIB_API rig_parse_mode(const char *s)
 {
 	int i;
@@ -242,6 +275,11 @@ rmode_t HAMLIB_API rig_parse_mode(const char *s)
 	return RIG_MODE_NONE;
 }
 
+/**
+ * \brief Convert enum RIG_MODE to alpha string
+ * \param mode RIG_MODE_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strrmode(rmode_t mode)
 {
 	int i;
@@ -256,7 +294,6 @@ const char * HAMLIB_API rig_strrmode(rmode_t mode)
 	return "";
 }
 
-
 static struct { 
 		vfo_t vfo;
 		const char *str;
@@ -272,6 +309,11 @@ static struct {
 		{ RIG_VFO_NONE, "" },
 };
 
+/**
+ * \brief Convert alpha string to enum RIG_VFO_...
+ * \param s input alpha string
+ * \return RIG_VFO_...
+ */
 vfo_t HAMLIB_API rig_parse_vfo(const char *s)
 {
 	int i;
@@ -282,6 +324,11 @@ vfo_t HAMLIB_API rig_parse_vfo(const char *s)
 	return RIG_VFO_NONE;
 }
 
+/**
+ * \brief Convert enum RIG_VFO_... to alpha string
+ * \param vfo RIG_VFO_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strvfo(vfo_t vfo)
 {
 	int i;
@@ -296,7 +343,6 @@ const char * HAMLIB_API rig_strvfo(vfo_t vfo)
 	return "";
 }
 
-
 static struct { 
 		setting_t func; 
 		const char *str;
@@ -332,6 +378,11 @@ static struct {
 	{ RIG_FUNC_NONE, "" },
 };
 
+/**
+ * \brief Convert alpha string to enum RIG_FUNC_...
+ * \param s input alpha string
+ * \return RIG_FUNC_...
+ */
 setting_t HAMLIB_API rig_parse_func(const char *s)
 {
 	int i;
@@ -343,6 +394,11 @@ setting_t HAMLIB_API rig_parse_func(const char *s)
 	return RIG_FUNC_NONE;
 }
 
+/**
+ * \brief Convert enum RIG_FUNC_... to alpha string
+ * \param func RIG_FUNC_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strfunc(setting_t func)
 {
 	int i;
@@ -357,7 +413,6 @@ const char * HAMLIB_API rig_strfunc(setting_t func)
 	return "";
 }
 
-
 static struct { 
 		setting_t level;
 		const char *str;
@@ -393,6 +448,11 @@ static struct {
 	{ RIG_LEVEL_NONE, "" },
 };
 
+/**
+ * \brief Convert alpha string to enum RIG_LEVEL_...
+ * \param s input alpha string
+ * \return RIG_LEVEL_...
+ */
 setting_t HAMLIB_API rig_parse_level(const char *s)
 {
 	int i;
@@ -404,6 +464,11 @@ setting_t HAMLIB_API rig_parse_level(const char *s)
 	return RIG_LEVEL_NONE;
 }
 
+/**
+ * \brief Convert enum RIG_LEVEL_... to alpha string
+ * \param level RIG_LEVEL_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strlevel(setting_t level)
 {
 	int i;
@@ -418,7 +483,6 @@ const char * HAMLIB_API rig_strlevel(setting_t level)
 	return "";
 }
 
-
 static struct { 
 		setting_t parm;
 		const char *str;
@@ -432,6 +496,11 @@ static struct {
 	{ RIG_PARM_NONE, "" },
 };
 
+/**
+ * \brief Convert alpha string to RIG_PARM_...
+ * \param s input alpha string
+ * \return RIG_PARM_...
+ */
 setting_t HAMLIB_API rig_parse_parm(const char *s)
 {
 	int i;
@@ -443,7 +512,11 @@ setting_t HAMLIB_API rig_parse_parm(const char *s)
 	return RIG_PARM_NONE;
 }
 
-
+/**
+ * \brief Convert enum RIG_PARM_... to alpha string
+ * \param parm RIG_PARM_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strparm(setting_t parm)
 {
 	int i;
@@ -458,7 +531,6 @@ const char * HAMLIB_API rig_strparm(setting_t parm)
 	return "";
 }
 
-
 static struct { 
 		vfo_op_t vfo_op;
 		const char *str;
@@ -479,6 +551,11 @@ static struct {
 	{ RIG_OP_NONE, "" },
 };
 
+/**
+ * \brief Convert alpha string to enum RIG_OP_...
+ * \param s alpha string
+ * \return RIG_OP_...
+ */
 vfo_op_t HAMLIB_API rig_parse_vfo_op(const char *s)
 {
 	int i;
@@ -490,6 +567,11 @@ vfo_op_t HAMLIB_API rig_parse_vfo_op(const char *s)
 	return RIG_OP_NONE;
 }
 
+/**
+ * \brief Convert enum RIG_OP_... to alpha string
+ * \param op RIG_OP_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strvfop(vfo_op_t op)
 {
 	int i;
@@ -504,7 +586,6 @@ const char * HAMLIB_API rig_strvfop(vfo_op_t op)
 	return "";
 }
 
-
 static struct { 
 		scan_t rscan;
 		const char *str;
@@ -520,6 +601,11 @@ static struct {
 	{ RIG_SCAN_NONE, "" },
 };
 
+/**
+ * \brief Convert alpha string to enum RIG_SCAN_...
+ * \param s alpha string
+ * \return RIG_SCAN_...
+ */
 scan_t HAMLIB_API rig_parse_scan(const char *s)
 {
 	int i;
@@ -529,10 +615,14 @@ scan_t HAMLIB_API rig_parse_scan(const char *s)
 			return scan_str[i].rscan;
 		}
 	}
-
 	return RIG_SCAN_NONE;
 }
 
+/**
+ * \brief Convert enum RIG_SCAN_... to alpha string
+ * \param rscan RIG_SCAN_...
+ * \return alpha string
+ */
 const char * HAMLIB_API rig_strscan(scan_t rscan)
 {
 	int i;
@@ -543,11 +633,29 @@ const char * HAMLIB_API rig_strscan(scan_t rscan)
 	for (i=0; scan_str[i].str != ""; i++)
 		if (rscan == scan_str[i].rscan)
 			return scan_str[i].str;
-
 	return "";
 }
 
+/**
+ * \brief convert enum RIG_RPT_SHIFT_... to printable character
+ * \param shift RIG_RPT_SHIFT_??
+ * \return alpha character
+ */
+const char * HAMLIB_API rig_strptrshift(rptr_shift_t shift)
+{
+	switch (shift) {
+	case RIG_RPT_SHIFT_MINUS: return "+";
+	case RIG_RPT_SHIFT_PLUS: return "-";
+	case RIG_RPT_SHIFT_NONE: return "None";
+	}
+	return NULL;
+}
 
+/**
+ * \brief Convert alpha char to enum RIG_RPT_SHIFT_...
+ * \param s alpha char
+ * \return RIG_RPT_SHIFT_...
+ */
 rptr_shift_t HAMLIB_API rig_parse_rptr_shift(const char *s)
 {
 	if (strcmp(s, "+") == 0)
@@ -558,3 +666,4 @@ rptr_shift_t HAMLIB_API rig_parse_rptr_shift(const char *s)
 		return RIG_RPT_SHIFT_NONE;
 }
 
+/** @} */

src/parallel.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - parallel communication low-level support
  *  Copyright (c) 2000-2005 by Stephane Fillod
  *
- *	$Id: parallel.c,v 1.5 2005-10-27 20:34:16 fillods Exp $
+ *	$Id: parallel.c,v 1.6 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,15 @@
  *
  */
 
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
+/**
+ * \brief Parallel Port IO
+ * \file parallel.c
+ */
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -80,7 +89,11 @@
 #define SP_ACTIVE_LOW_BITS	0x80
 
 
-/*
+/**
+ * \brief Open Parallel Port
+ * \param port
+ * \return file descriptor
+ *
  * TODO: to be called before exiting: atexit(parport_cleanup)
  * void parport_cleanup() { ioctl(fd, PPRELEASE); }
  */
@@ -129,6 +142,10 @@ int par_open(hamlib_port_t *port)
 	return fd;
 }
 
+/**
+ * \brief Close Parallel Port
+ * \param port
+ */
 int par_close(hamlib_port_t *port)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -140,6 +157,11 @@ int par_close(hamlib_port_t *port)
 	return close(port->fd);
 }
 
+/**
+ * \brief Send data on Parallel port
+ * \param port
+ * \param data
+ */
 int HAMLIB_API par_write_data(hamlib_port_t *port, unsigned char data)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -161,6 +183,11 @@ int HAMLIB_API par_write_data(hamlib_port_t *port, unsigned char data)
 	return -RIG_ENIMPL;
 }
 
+/**
+ * \brief Receive data on Parallel port
+ * \param port
+ * \param data
+ */
 int HAMLIB_API par_read_data(hamlib_port_t *port, unsigned char *data)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -185,7 +212,11 @@ int HAMLIB_API par_read_data(hamlib_port_t *port, unsigned char *data)
 	return -RIG_ENIMPL;
 }
 
-
+/**
+ * \brief Set control data for Parallel Port
+ * \param port
+ * \param control
+ */
 int HAMLIB_API par_write_control(hamlib_port_t *port, unsigned char control)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -224,6 +255,11 @@ int HAMLIB_API par_write_control(hamlib_port_t *port, unsigned char control)
 	return -RIG_ENIMPL;
 }
 
+/**
+ * \brief Read control data for Parallel Port
+ * \param port
+ * \param control
+ */
 int HAMLIB_API par_read_control(hamlib_port_t *port, unsigned char *control)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -252,7 +288,12 @@ int HAMLIB_API par_read_control(hamlib_port_t *port, unsigned char *control)
 	return -RIG_ENIMPL;
 }
 
-
+/**
+ * \brief Get parallel port status
+ * \param port
+ * \param status
+ * \return RIG_OK or < 0 for error
+ */
 int HAMLIB_API par_read_status(hamlib_port_t *port, unsigned char *status)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -281,7 +322,11 @@ int HAMLIB_API par_read_status(hamlib_port_t *port, unsigned char *status)
 	return -RIG_ENIMPL;
 }
 
-
+/**
+ * \brief Get a lock on the Parallel Port
+ * \param port
+ * \return RIG_OK or < 0
+ */
 int HAMLIB_API par_lock(hamlib_port_t *port)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -297,6 +342,11 @@ int HAMLIB_API par_lock(hamlib_port_t *port)
 	return -RIG_ENIMPL;
 }
 
+/**
+ * \brief Release lock on Parallel Port
+ * \param port
+ * \return RIG_OK or < 0
+ */
 int HAMLIB_API par_unlock(hamlib_port_t *port)
 {
 #ifdef HAVE_LINUX_PPDEV_H
@@ -312,7 +362,12 @@ int HAMLIB_API par_unlock(hamlib_port_t *port)
 	return -RIG_ENIMPL;
 }
 
-
+/**
+ * \brief Set or unset Push to talk bit on Parallel Port
+ * \param p
+ * \param pttx RIG_PTT_ON --> Set PTT
+ * \return RIG_OK or < 0 error
+ */
 int par_ptt_set(hamlib_port_t *p, ptt_t pttx)
 {
 	switch(p->type.ptt) {
@@ -328,7 +383,6 @@ int par_ptt_set(hamlib_port_t *p, ptt_t pttx)
 			reg |=   1 << p->parm.parallel.pin;
 		else
 			reg &= ~(1 << p->parm.parallel.pin);
-
 		return par_write_data(p, reg);
 		}
 	default:
@@ -336,12 +390,14 @@ int par_ptt_set(hamlib_port_t *p, ptt_t pttx)
 						p->type.ptt);
 		return -RIG_EINVAL;
 	}
-
 	return RIG_OK;
 }
 
-/*
+/**
- * assumes pttx not NULL
+ * \brief Get state of Push to Talk from Parallel Port
+ * \param p
+ * \param pttx return value (must be non NULL)
+ * \return RIG_OK or < 0 error
  */
 int par_ptt_get(hamlib_port_t *p, ptt_t *pttx)
 {
@@ -361,12 +417,14 @@ int par_ptt_get(hamlib_port_t *p, ptt_t *pttx)
 						p->type.ptt);
 		return -RIG_ENAVAIL;
 	}
-
 	return RIG_OK;
 }
 
-/*
+/**
- * assumes dcdx not NULL
+ * \brief get Data Carrier Detect (squelch) from Parallel Port
+ * \param p
+ * \param dcdx return value (Must be non NULL)
+ * \return RIG_OK or < 0 error
  */
 int par_dcd_get(hamlib_port_t *p, dcd_t *dcdx)
 {
@@ -386,7 +444,7 @@ int par_dcd_get(hamlib_port_t *p, dcd_t *dcdx)
 						p->type.dcd);
 		return -RIG_ENAVAIL;
 	}
-
 	return RIG_OK;
 }
 
+/** @} */

src/register.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - provides registering for dynamically loadable backends.
  *  Copyright (c) 2000-2005 by Stephane Fillod
  *
- *	$Id: register.c,v 1.23 2005-04-04 18:30:56 fillods Exp $
+ *	$Id: register.c,v 1.24 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,13 @@
  *
  */
 
+/**
+ * \brief Dynamic registration of backends
+ * \file register.c
+ *
+ * doc todo: Let's explain what's going on here!
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -36,7 +43,6 @@
 
 #include <hamlib/rig.h>
 
-
 #ifndef PATH_MAX
 # define PATH_MAX       1024
 #endif
@@ -56,7 +62,6 @@ static struct {
 	rig_model_t (* be_probe_all)(hamlib_port_t*, rig_probe_func_t, rig_ptr_t);
 } rig_backend_list[RIG_BACKEND_MAX] = RIG_BACKEND_LIST;
 
-
 /*
  * This struct to keep track of known rig models.
  * It is chained, and used in a hash table, see below.

src/rig.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - main file
  *  Copyright (c) 2000-2006 by Stephane Fillod and Frank Singleton
  *
- *	$Id: rig.c,v 1.93 2006-10-07 13:08:19 csete Exp $
+ *	$Id: rig.c,v 1.94 2006-10-15 00:27:51 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,23 +20,27 @@
  *
  */
 
+/**
+ * \addtogroup rig
+ * @{
+ */
+
 /**
  * \file src/rig.c
- * \ingroup rig
  * \brief Ham Radio Control Libraries interface
  * \author Stephane Fillod
  * \author Frank Singleton
  * \date 2000-2006
  *
- * Hamlib interface is a frontend implementing wrapper functions.
+ * Hamlib provides a user-callable API, a set of "front-end" routines that
+ * call rig-specific "back-end" routines whichactually communicate with 
+ * the physical rig.
  */
 
-
 /*! \page rig Rig (radio) interface
  *
- * Although the word rig can stand for lot of thinfs, we are
+ * For us, a "rig" is an item of general remote controllable radio equipment.
- * understanding it as general remote controllable radio equipment,
+ * Generally, there are a VFO settings, gain controls, etc.
- * with a so-called tunable VFO.
  */
 
 /**
@@ -64,6 +68,7 @@
 
 /**
  * \brief Hamlib release number
+ * The version number has the format x.y.z
  */
 const char hamlib_version[] = "Hamlib version " PACKAGE_VERSION;
 
@@ -103,7 +108,6 @@ struct opened_rig_l {
 };
 static struct opened_rig_l *opened_rig_list = { NULL };
 
-
 /*
  * Careful, the order must be the same as their RIG_E* counterpart!
  * TODO: localise the messages..
@@ -2766,3 +2770,4 @@ const char* HAMLIB_API rig_get_info(RIG *rig)
 	return rig->caps->get_info(rig);
 }
 
+/*! @} */

src/rot_conf.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - rotator configuration interface
  *  Copyright (c) 2000-2004 by Stephane Fillod
  *
- *	$Id: rot_conf.c,v 1.5 2005-04-04 18:31:00 fillods Exp $
+ *	$Id: rot_conf.c,v 1.6 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,16 @@
  *
  */
 
+/**
+ * \addtogroup rotator
+ * @{
+ */
+
+/**
+ * \brief Rotator Configuration Interface
+ * \file rot_conf.c
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -101,8 +111,13 @@ static const struct confparams rotfrontend_cfg_params[] = {
 	{ RIG_CONF_END, NULL, }
 };
 
-/*
+/**
- * frontrot_set_conf
+ * \brief Set rotator state info from alpha input
+ * \param rot
+ * \param token TOK_... specifying which info to set
+ * \param val input
+ * \return RIG_OK or < 0 error
+ *
  * assumes rot!=NULL, val!=NULL
  * TODO: check format of val before doing atoi().
  */
@@ -180,9 +195,12 @@ int frontrot_set_conf(ROT *rot, token_t token, const char *val)
 	return RIG_OK;
 }
 
-/*
+/**
- * frontrot_get_conf
+ * \brief Get data from rotator state in alpha form
- * assumes rot!=NULL, val!=NULL
+ * \param rot non-null
+ * \param token TOK_... specifying which data to get
+ * \param val result non-null
+ * \return RIG_OK or < 0 if error
  */
 int frontrot_get_conf(ROT *rot, token_t token, char *val)
 {
@@ -236,7 +254,6 @@ int frontrot_get_conf(ROT *rot, token_t token, char *val)
 		}
 		strcpy(val, s);
 		break;
-
 	case TOK_MIN_AZ:
 		sprintf(val, "%f", rs->min_az);
 		break;
@@ -249,17 +266,18 @@ int frontrot_get_conf(ROT *rot, token_t token, char *val)
 	case TOK_MAX_EL:
 		sprintf(val, "%f", rs->max_el);
 		break;
-
 	default:
 		return -RIG_EINVAL;
 	}
-
 	return RIG_OK;
 }
 
-/*
+/**
- * rot_token_foreach
+ * \brief Executes cfunc on all the elements stored in the conf table
- * executes cfunc on all the elements stored in the conf table
+ * \param rot non-null
+ * \param cfunc function(..)
+ * \param data
+ * 
  * start first with backend conf table, then finish with frontend table
  */
 int HAMLIB_API rot_token_foreach(ROT *rot, int (*cfunc)(const struct confparams *, rig_ptr_t), rig_ptr_t data)
@@ -279,8 +297,11 @@ int HAMLIB_API rot_token_foreach(ROT *rot, int (*cfunc)(const struct confparams
 }
 
 
-/*
+/**
- * lookup conf token by its name, return pointer to confparams struct.
+ * \brief lookup conf token by its name, return pointer to confparams struct.
+ * \param rot
+ * \param name
+ * \return confparams or NULL
  *
  * lookup backend config table first, then fall back to frontend.
  * TODO: should use Lex to speed it up, strcmp hurts!
@@ -300,8 +321,11 @@ const struct confparams * HAMLIB_API rot_confparam_lookup(ROT *rot, const char *
 	return NULL;
 }
 
-/*
+/**
- * Simple lookup returning token id assicated with name
+ * \brief Simple lookup returning token id associated with name
+ * \param rot
+ * \param name
+ * \return token enum 
  */
 token_t HAMLIB_API rot_token_lookup(ROT *rot, const char *name)
 {
@@ -314,3 +338,4 @@ token_t HAMLIB_API rot_token_lookup(ROT *rot, const char *name)
 	return cfp->token;
 }
 
+/** @} */

src/rot_reg.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - provides registering for dynamically loadable backends.
  *  Copyright (c) 2000-2004 by Stephane Fillod
  *
- *	$Id: rot_reg.c,v 1.9 2005-04-04 18:31:00 fillods Exp $
+ *	$Id: rot_reg.c,v 1.10 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,14 @@
  *
  */
 
+/**
+ * \brief Dynamic registration of rotator backends
+ * \file rot_reg.c
+ *
+ * Similar to register.c
+ * doc todo: Let's explain what's going on here!
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

src/rotator.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - main file
  *  Copyright (c) 2000-2006 by Stephane Fillod and Frank Singleton
  *
- *	$Id: rotator.c,v 1.20 2006-10-07 13:08:19 csete Exp $
+ *	$Id: rotator.c,v 1.21 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,9 +20,13 @@
  *
  */
 
+/**
+ * \addtogroup rotator
+ * @{
+ */
+
 /**
  * \file src/rotator.c
- * \ingroup rot
  * \brief Rotator interface
  * \author Stephane Fillod
  * \date 2000-2006
@@ -686,3 +690,4 @@ const char* HAMLIB_API rot_get_info(ROT *rot)
 	return rot->caps->get_info(rot);
 }
 
+/*! @} */

src/serial.c

@@ -4,7 +4,7 @@
  *  Parts of the PTT handling are derived from soundmodem, an excellent
  *  ham packet softmodem written by Thomas Sailer, HB9JNX.
  *
- *	$Id: serial.c,v 1.44 2005-04-03 12:27:17 fillods Exp $
+ *	$Id: serial.c,v 1.45 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -22,6 +22,16 @@
  *
  */
 
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
+/**
+ * \brief Serial port IO
+ * \file serial.c
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -72,19 +82,11 @@
 #include <sys/ioccom.h>
 #endif
 
-/*
+/**
- * Open serial port using rig.state data
+ * \brief Open serial port using rig.state data
- *
+ * \param rp port data structure (must spec port id eg /dev/ttyS1)
- *
+ * \return RIG_OK or < 0 if error
- * input: ptr to rig.state structure, with serial port
- *        populated. (eg: "/dev/ttyS1").
- * 
- * returns:
- *
- * 0 if OK or negative value on error.
- *
  */
-
 int HAMLIB_API serial_open(hamlib_port_t *rp) {
 
   int fd;				/* File descriptor for the port */
@@ -118,7 +120,11 @@ int HAMLIB_API serial_open(hamlib_port_t *rp) {
   return RIG_OK;
 }
 
-
+/**
+ * \brief Set up Serial port according to requests in port
+ * \param rp
+ * \return RIG_OK or < 0
+ */
 int HAMLIB_API serial_setup(hamlib_port_t *rp)
 {
   int fd;
@@ -356,10 +362,11 @@ int HAMLIB_API serial_setup(hamlib_port_t *rp)
 }
 
 
-/*
+/**
- * Flush all characters waiting in RX buffer.
+ * \brief Flush all characters waiting in RX buffer.
+ * \param p
+ * \return RIG_OK
  */
-
 int HAMLIB_API serial_flush(hamlib_port_t *p )
 {
   tcflush(p->fd, TCIFLUSH);
@@ -367,16 +374,32 @@ int HAMLIB_API serial_flush(hamlib_port_t *p )
   return RIG_OK;
 }
 
+/**
+ * \brief Open serial port
+ * \param p
+ * \return fd
+ */
 int ser_open(hamlib_port_t *p)
 {
 	return (p->fd = OPEN(p->pathname, O_RDWR | O_NOCTTY | O_NDELAY));
 }
 
+/**
+ * \brief Close serial port
+ * \param p fd
+ * \return RIG_OK or < 0
+ */
 int ser_close(hamlib_port_t *p)
 {
 	return CLOSE(p->fd);
 }
 
+/**
+ * \brief Set Request to Send (RTS) bit
+ * \param p
+ * \param state true/false
+ * \return RIG_OK or < 0
+ */
 int HAMLIB_API ser_set_rts(hamlib_port_t *p, int state)
 {
 	unsigned int y = TIOCM_RTS;
@@ -396,9 +419,10 @@ int HAMLIB_API ser_set_rts(hamlib_port_t *p, int state)
 #endif
 }
 
-/*
+/**
- * assumes state not NULL
+ * \brief Get RTS bit
- * p is supposed to be &rig->state.rigport
+ * \param p supposed to be &rig->state.rigport
+ * \param state non-NULL
  */
 int HAMLIB_API ser_get_rts(hamlib_port_t *p, int *state)
 {
@@ -411,6 +435,12 @@ int HAMLIB_API ser_get_rts(hamlib_port_t *p, int *state)
   return retcode < 0 ? -RIG_EIO : RIG_OK;
 }
 
+/**
+ * \brief Set Data Terminal Ready (DTR) bit
+ * \param p
+ * \param state true/false
+ * \return RIG_OK or < 0
+ */
 int HAMLIB_API ser_set_dtr(hamlib_port_t *p, int state)
 {
 	unsigned int y = TIOCM_DTR;
@@ -430,6 +460,11 @@ int HAMLIB_API ser_set_dtr(hamlib_port_t *p, int state)
 #endif
 }
 
+/**
+ * \brief Get DTR bit
+ * \param p supposed to be &rig->state.rigport
+ * \param state non-NULL
+ */
 int HAMLIB_API ser_get_dtr(hamlib_port_t *p, int *state)
 {
   int retcode;
@@ -441,6 +476,12 @@ int HAMLIB_API ser_get_dtr(hamlib_port_t *p, int *state)
   return retcode < 0 ? -RIG_EIO : RIG_OK;
 }
 
+/**
+ * \brief Set Break
+ * \param p
+ * \param state (ignored?)
+ * \return RIG_OK or < 0
+ */
 int HAMLIB_API ser_set_brk(hamlib_port_t *p, int state)
 {
 #if defined(TIOCSBRK) && defined(TIOCCBRK)
@@ -451,9 +492,10 @@ int HAMLIB_API ser_set_brk(hamlib_port_t *p, int state)
 #endif
 }
 
-/*
+/**
- * assumes state not NULL
+ * \brief Get Carrier (CI?) bit
- * p is supposed to be &rig->state.rigport
+ * \param p supposed to be &rig->state.rigport
+ * \param state non-NULL
  */
 int HAMLIB_API ser_get_car(hamlib_port_t *p, int *state)
 {
@@ -466,6 +508,11 @@ int HAMLIB_API ser_get_car(hamlib_port_t *p, int *state)
   return retcode < 0 ? -RIG_EIO : RIG_OK;
 }
 
+/**
+ * \brief Get Clear to Send (CTS) bit
+ * \param p supposed to be &rig->state.rigport
+ * \param state non-NULL
+ */
 int HAMLIB_API ser_get_cts(hamlib_port_t *p, int *state)
 {
   int retcode;
@@ -477,6 +524,11 @@ int HAMLIB_API ser_get_cts(hamlib_port_t *p, int *state)
   return retcode < 0 ? -RIG_EIO : RIG_OK;
 }
 
+/**
+ * \brief Get Data Set Ready (DSR) bit
+ * \param p supposed to be &rig->state.rigport
+ * \param state non-NULL
+ */
 int HAMLIB_API ser_get_dsr(hamlib_port_t *p, int *state)
 {
   int retcode;
@@ -488,3 +540,4 @@ int HAMLIB_API ser_get_dsr(hamlib_port_t *p, int *state)
   return retcode < 0 ? -RIG_EIO : RIG_OK;
 }
 
+/** @} */

src/settings.c

@@ -1,6 +1,10 @@
 /**
- * \file src/settings.c
+ * \addtogroup rig
- * \ingroup rig
+ * @{
+ */
+
+/**
+ * \file settings.c
  * \brief func/level/parm interface
  * \author Stephane Fillod
  * \date 2000-2006
@@ -12,7 +16,7 @@
  *  Hamlib Interface - func/level/parm
  *  Copyright (c) 2000-2006 by Stephane Fillod
  *
- *	$Id: settings.c,v 1.7 2006-02-26 19:29:19 fillods Exp $
+ *	$Id: settings.c,v 1.8 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -630,4 +634,4 @@ int HAMLIB_API rig_setting2idx(setting_t s)
 	return 0;
 }
 
-
+/*! @} */

src/tones.c

@@ -1,6 +1,10 @@
+/**
+ * \addtogroup rig
+ * @{
+ */
+
 /**
  * \file src/tones.c
- * \ingroup rig
  * \brief CTCSS and DCS interface and tables
  * \author Stephane Fillod
  * \date 2000-2006
@@ -9,7 +13,7 @@
  *  Hamlib Interface - CTCSS and DCS interface and tables
  *  Copyright (c) 2000-2006 by Stephane Fillod
  *
- *	$Id: tones.c,v 1.9 2006-02-26 19:29:19 fillods Exp $
+ *	$Id: tones.c,v 1.10 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -443,3 +447,4 @@ int HAMLIB_API rig_get_dcs_sql(RIG *rig, vfo_t vfo, tone_t *code)
 	return retcode;
 }
 
+/*! @} */

src/usb_port.c

@@ -1,8 +1,8 @@
 /*
- *  Hamlib Interface - parallel communication low-level support
+ *  Hamlib Interface - USB communication low-level support
  *  Copyright (c) 2000-2005 by Stephane Fillod
  *
- *	$Id: usb_port.c,v 1.3 2006-02-20 22:41:17 fillods Exp $
+ *	$Id: usb_port.c,v 1.4 2006-10-15 00:27:52 aa6e Exp $
  *
  *   This library is free software; you can redistribute it and/or modify
  *   it under the terms of the GNU Library General Public License as
@@ -20,6 +20,18 @@
  *
  */
 
+/**
+ * \addtogroup rig_internal
+ * @{
+ */
+
+/**
+ * \brief USB IO
+ * \file usb_port.c
+ *
+ * doc todo: deal with defined(HAVE_LIBUSB)... quashing the doc process.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -43,7 +55,11 @@
 #include <usb.h>
 #include "usb_port.h"
 
-
+/**
+ * \brief Find USB device
+ * \param port
+ * \return usb_device
+ */
 struct usb_device * find_device(const hamlib_port_t *port)
 {
 	struct usb_bus *p;
@@ -117,8 +133,6 @@ int usb_port_open(hamlib_port_t *port)
   return RIG_OK;
 }
 
-
-
 int usb_port_close(hamlib_port_t *port)
 {
 	struct usb_dev_handle *udh = port->handle;
@@ -140,3 +154,5 @@ int usb_port_close(hamlib_port_t *port)
 }
 
 #endif	/* defined(HAVE_LIBUSB) && defined(HAVE_USB_H) */
+
+/** @} */