Fully document amplist.h

Create a new topic group of 'amplist' to separate the list of amplifier
models from the main Amplifier API group.

doc/index.doxygen

@@ -195,6 +195,7 @@ GNU/Linux.
  * \defgroup rotator Rotator API
  * \defgroup rot_internal Rotator Internal API
  * \defgroup amplifier Amplifier API
+ * \defgroup amplist Amplifier model list
  * \defgroup amp_internal Amplifier Internal API
  * \defgroup port Port data structure for accessing devices
  * \defgroup utilities Utility Routines API

include/hamlib/amplist.h

@@ -25,17 +25,12 @@
 #ifndef _AMPLIST_H
 #define _AMPLIST_H 1
 
-//! @cond Doxygen_Suppress
-#define AMP_MAKE_MODEL(a,b) ((a)*100+(b))
-#define AMP_BACKEND_NUM(a) ((a)/100)
-//! @endcond
-
-
 /**
- * \addtogroup amplifier
+ * \addtogroup amplist
  * @{
  */
 
+
 /**
  * \brief Hamlib amplifier model definitions.
  *
@@ -55,6 +50,27 @@
  * wishes to use which is passed to the amp_init() API call.
  */
 
+/**
+ * \brief The amp model number is held in a signed integer.
+ *
+ * Model numbers are a simple decimal value that increments by a value of
+ * 100 for each backend, e.g. the `DUMMY` backend has model numbers 1
+ * to 100, the `ELECRAFT` backend has model numbers 201 to 300 and so on
+ * (101 to 200 is currently unassigned).
+ *
+ * \note A limitation is that with ::amp_model_t being a signed integer that on
+ * some systems such a value may be 16 bits.  This limits the number of backends
+ * to 326 of 100 models each (32768 / 100 thus leaving only 68 models for
+ * backend number 327 so round down to 326).  So far this doesn't seem like an
+ * extreme limitation.
+ *
+ * \sa amp_model_t
+ */
+#define AMP_MAKE_MODEL(a,b) ((a)*100+(b))
+
+/** Convenience macro to derive the backend family number from the model number. */
+#define AMP_BACKEND_NUM(a) ((a)/100)
+
 
 /**
  * \brief A macro that returns the model number for an unknown model.
@@ -67,71 +83,63 @@
 #define AMP_MODEL_NONE 0
 
 
+/** The `DUMMY` family.  Also contains network models. */
+#define AMP_DUMMY 0
+/** Used in amp_reg.c for the `be_name`. */
+#define AMP_BACKEND_DUMMY "dummy"
 /**
- * \brief A macro that returns the model number for the DUMMY backend.
+ * \brief A macro that returns the model number for `DUMMY`.
  *
- * \def AMP_MODEL_DUMMY
- *
- * The DUMMY backend, as the name suggests, is a backend which performs no
+ * The `DUMMY` model, as the name suggests, is a model 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.
  */
-/**
- * \brief A macro that returns the model number for the NETAMPCTL backend.
- *
- * \def AMP_MODEL_NETAMPCTL
- *
- * The NETAMPCTL backend allows use of the `ampctld` daemon through the normal
- * Hamlib API.
- */
-//! @cond Doxygen_Suppress
-#define AMP_DUMMY 0
-#define AMP_BACKEND_DUMMY "dummy"
-//! @endcond
 #define AMP_MODEL_DUMMY AMP_MAKE_MODEL(AMP_DUMMY, 1)
+/**
+ * \brief A macro that returns the model number for `NETAMPCTL`.
+ *
+ * The `NETAMPCTL` model allows use of the `ampctld` daemon through the normal
+ * Hamlib C API.
+ */
 #define AMP_MODEL_NETAMPCTL AMP_MAKE_MODEL(AMP_DUMMY, 2)
 
 
+/** The `ELECRAFT` family. */
+#define AMP_ELECRAFT 2
+/** Used in amp_reg.c for the `be_name`. */
+#define AMP_BACKEND_ELECRAFT "elecraft"
 /**
- * \brief A macro that returns the model number of the KPA1500 backend.
+ * \brief A macro that returns the model number of `KPA1500`.
  *
- * \def AMP_MODEL_ELECRAFT_KPA1500
- *
- * The KPA1500 backend can be used with amplifiers that support the Elecraft
+ * The `KPA1500` model can be used with amplifiers that support the Elecraft
  * KPA-1500 protocol.
  */
-//! @cond Doxygen_Suppress
-#define AMP_ELECRAFT 2
-#define AMP_BACKEND_ELECRAFT "elecraft"
-//! @endcond
 #define AMP_MODEL_ELECRAFT_KPA1500 AMP_MAKE_MODEL(AMP_ELECRAFT, 1)
 //#define AMP_MODEL_ELECRAFT_KPA500 AMP_MAKE_MODEL(AMP_ELECRAFT, 2)
 
+
+/** The `GEMINI` family. */
+#define AMP_GEMINI 3
+/** Used in amp_reg.c for the `be_name`. */
+#define AMP_BACKEND_GEMINI "gemini"
 /**
- * \brief A macro that returns the model number of the DX1200 backend.
- *
- * \def AMP_MODEL_GEMINI_DX1200
+ * \brief A macro that returns the model number of `DX1200`.
  *
  * The Gemini DX1200 covers 160 trhough 4 meters.
  */
-//! @cond Doxygen_Suppress
-#define AMP_GEMINI 3
-#define AMP_BACKEND_GEMINI "gemini"
-//! @endcond
 #define AMP_MODEL_GEMINI_DX1200 AMP_MAKE_MODEL(AMP_GEMINI, 1)
 
+
+/** The `EXPERT` family. */
+#define AMP_EXPERT 4
+/** Used in amp_reg.c for the `be_name`. */
+#define AMP_BACKEND_EXPERT "expert"
 /**
- * \brief A macro that returns the model number of the FA backend.
- *
- * \def AMP_MODEL_EXPERT_FA
+ * \brief A macro that returns the model number of `FA`.
  *
  * The Expert FA series of amplifiers is supported by this backend.
  */
-//! @cond Doxygen_Suppress
-#define AMP_EXPERT 4
-#define AMP_BACKEND_EXPERT "expert"
-//! @endcond
 #define AMP_MODEL_EXPERT_FA AMP_MAKE_MODEL(AMP_EXPERT, 1)