documentation

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

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.117 2006-10-17 01:23:38 aa6e Exp $
+ *	$Id: rig.h,v 1.118 2006-10-28 03:49:05 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
@@ -1071,8 +1071,8 @@ struct rig_caps {
   gran_t level_gran[RIG_SETTING_MAX];	/*!< level granularity (i.e. steps) */
   gran_t parm_gran[RIG_SETTING_MAX];	/*!< parm granularity (i.e. steps) */
 
-  const struct confparams *extparms;	/*!< Extension parm list */
-  const struct confparams *extlevels;	/*!< Extension level list */
+  const struct confparams *extparms;	/*!< Extension parm list, \sa ext.c */
+  const struct confparams *extlevels;	/*!< Extension level list, \sa ext.c */
 
   const tone_t *ctcss_list;	/*!< CTCSS tones list, zero ended */
   const tone_t *dcs_list;	/*!< DCS code list, zero ended */

src/ext.c

@@ -2,7 +2,7 @@
  *  Hamlib Interface - extrq parameter interface
  *  Copyright (c) 2000-2004 by Stephane Fillod
  *
- *	$Id: ext.c,v 1.5 2006-10-15 00:27:51 aa6e Exp $
+ *	$Id: ext.c,v 1.6 2006-10-28 03:49:46 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,11 +20,19 @@
  *
  */
 /**
- * \file ext.c
- * \brief Ext. request parameter interface
+ * \addtogroup rig
+ * @{
  */
 
-/* doc todo: Are these in the Hamlib API? */
+/**
+ * \file ext.c
+ * \brief Extension request parameter interface
+ *
+ * An open-ended set of extension parameters and levels are available for each rig,
+ * as provided in the rigcaps extparms and extlevels lists.  These provide a way
+ * to work with rig-specific functions that don't fit into the basic "virtual rig" of
+ * Hamlib.  See icom/ic746.c for an example.
+ */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
@@ -42,10 +50,12 @@
 
 
 
-/*
- * rig_ext_level_foreach
- * executes cfunc on all the elements stored in the extlevels table
- */
+/**
+ * \param rig
+ * \param cfunc
+ * \param data
+  * \brief Executes cfunc on all the elements stored in the extlevels table
+*/
 int HAMLIB_API rig_ext_level_foreach(RIG *rig, int (*cfunc)(RIG *, const struct confparams *, rig_ptr_t), rig_ptr_t data)
 {
 	const struct confparams *cfp;
@@ -60,9 +70,11 @@ int HAMLIB_API rig_ext_level_foreach(RIG *rig, int (*cfunc)(RIG *, const struct
 	return RIG_OK;
 }
 
-/*
- * rig_ext_parm_foreach
- * executes cfunc on all the elements stored in the extparms table
+/**
+ * \param rig
+ * \param cfunc The function to be called
+ * \param data The data
+ * \brief Executes cfunc on all the elements stored in the extparms table
  */
 int HAMLIB_API rig_ext_parm_foreach(RIG *rig, int (*cfunc)(RIG *, const struct confparams *, rig_ptr_t), rig_ptr_t data)
 {
@@ -78,14 +90,15 @@ int HAMLIB_API rig_ext_parm_foreach(RIG *rig, int (*cfunc)(RIG *, const struct c
 	return RIG_OK;
 }
 
-
-
-/*
- * lookup ext token by its name, return pointer to confparams struct.
+/**
+ * \param rig
+ * \param name
+ * \brief lookup ext token by its name, return pointer to confparams struct.
  *
- * lookup extlevels table first, then fall back to extparms.
+ * Lookup extlevels table first, then fall back to extparms.
  *
  * Returns NULL if nothing found
+ *
  * TODO: should use Lex to speed it up, strcmp hurts!
  */
 const struct confparams * HAMLIB_API rig_ext_lookup(RIG *rig, const char *name)
@@ -104,8 +117,10 @@ const struct confparams * HAMLIB_API rig_ext_lookup(RIG *rig, const char *name)
 	return NULL;
 }
 
-/*
- * lookup ext token, return pointer to confparams struct.
+/**
+ * \param rig
+ * \param token
+ * \brief lookup ext token, return pointer to confparams struct.
  *
  * lookup extlevels table first, then fall back to extparms.
  *
@@ -127,8 +142,10 @@ const struct confparams * HAMLIB_API rig_ext_lookup_tok(RIG *rig, token_t token)
 	return NULL;
 }
 
-/*
- * Simple lookup returning token id assicated with name
+/**
+ * \param rig
+ * \param name
+ * \brief Simple lookup returning token id assicated with name
  */
 token_t HAMLIB_API rig_ext_token_lookup(RIG *rig, const char *name)
 {
@@ -141,4 +158,4 @@ token_t HAMLIB_API rig_ext_token_lookup(RIG *rig, const char *name)
 	return cfp->token;
 }
 
-
+/** @} */

src/token.h

@@ -2,7 +2,7 @@
  *  Hamlib Interface - token header
  *  Copyright (c) 2000-2003 by Stephane Fillod
  *
- *	$Id: token.h,v 1.4 2006-10-17 14:28:52 aa6e Exp $
+ *	$Id: token.h,v 1.5 2006-10-28 03:49:46 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
@@ -21,7 +21,7 @@
  */
 
 /**
- * \addtogroup rig
+ * \addtogroup rig_internal
  * @{
  */
 
@@ -90,9 +90,9 @@
 #define TOK_POLL_INTERVAL	TOKEN_FRONTEND(111)
 /** \brief rig: International Telecommunications Union region no. */
 #define TOK_ITU_REGION	TOKEN_FRONTEND(120)
-
 /*
  * rotator specific tokens
+ * (strictly, should be documented as rotator_internal)
  */
 /** \brief rot: Minimum Azimuth */
 #define TOK_MIN_AZ	TOKEN_FRONTEND(110)
@@ -106,4 +106,4 @@
 
 #endif /* _TOKEN_H */
 
-/** @} */
+/** @} */ /* rig_internal definitions */