Add Doxygen support to port.h

doc/Makefile.am

@@ -9,6 +9,7 @@ SRCDOCLST = \
 	../include/hamlib/amplifier.h \
 	../include/hamlib/amplist.h \
 	../include/hamlib/amp_state.h \
+	../include/hamlib/port.h \
 	../include/hamlib/rig.h \
 	../include/hamlib/rotator.h \
 	../include/hamlib/rotlist.h \

doc/hamlib.cfg.in

@@ -58,6 +58,7 @@ ENABLED_SECTIONS      = ""
 PREDEFINED            = DOXYGEN "DOC_HIDDEN"
 JAVADOC_AUTOBRIEF     = NO
 OPTIMIZE_OUTPUT_FOR_C = YES
+DISTRIBUTE_GROUP_DOC  = YES
 
 MAN_LINKS             = NO
 MACRO_EXPANSION       = YES

doc/index.doxygen

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

include/hamlib/port.h

@@ -24,23 +24,40 @@
 #ifndef _HL_PORT_H
 #define _HL_PORT_H 1
 
+
 __BEGIN_DECLS
+
+/**
+ * \addtogroup port
+ * @{
+ */
+
+/**
+ * \brief Hamlib port data structures.
+ *
+ * \file port.h
+ *
+ * This file contains the data structures and declarations for the Hamlib
+ * port Application Programming Interface (API).
+ */
+
 /**
  * \brief Port definition
  *
  * Of course, looks like OO painstakingly programmed in C, sigh.
+ *
+ * \warning
+ * DO NOT CHANGE THIS STRUCTURE AT ALL UNTIL 5.0.
+ * Right now it is static inside the rig structure.
+ * 5.0 will change it to a pointer which can then be added to.
+ * At that point only add to the end of the structure.
  */
-//! @cond Doxygen_Suppress
-// DO NOT CHANGE THIS STRUCTURE ALL UNTIL 5.0
-// Right now it is static inside rig structure
-// 5.0 will change it to a pointer which can then be added to
-// At that point only add to the end of the structure
 typedef struct hamlib_port {
     union {
-        rig_port_t rig;     /*!< Communication port type */
+        rig_port_t rig;     /*!< Communication port of #rig_port_e type. */
-        ptt_type_t ptt;     /*!< PTT port type */
+        ptt_type_t ptt;     /*!< PTT port of #ptt_type_e type. */
-        dcd_type_t dcd;     /*!< DCD port type */
+        dcd_type_t dcd;     /*!< DCD port of #dcd_type_e type. */
-    } type;
+    } type;                 /*!< Type of port in use.*/
 
     int fd;                 /*!< File descriptor */
     void *handle;           /*!< handle for USB */
@@ -109,14 +126,20 @@ typedef struct hamlib_port {
 } hamlib_port_t;
 
 
-// DO NOT CHANGE THIS STRUCTURE AT ALL
+/**
-// Will be removed in 5.0
+ * \deprecated
+ * This structure will be removed in 5.0 and should not be used in new code.
+ *
+ * \warning
+ * DO NOT CHANGE THIS STRUCTURE AT ALL!
+ * Will be removed in 5.0.
+ */
 typedef struct hamlib_port_deprecated {
     union {
         rig_port_t rig;     /*!< Communication port type */
         ptt_type_t ptt;     /*!< PTT port type */
         dcd_type_t dcd;     /*!< DCD port type */
-    } type;
+    } type;                 /*!< Type of port in use.*/
 
     int fd;                 /*!< File descriptor */
     void *handle;           /*!< handle for USB */
@@ -171,21 +194,27 @@ typedef struct hamlib_port_deprecated {
     int client_port;      /*!< client socket port for tcp connection */
     RIG *rig;             /*!< our parent RIG device */
 } hamlib_port_t_deprecated;
-//! @endcond
 
 #if !defined(__APPLE__) || !defined(__cplusplus)
+//! @deprecated Obsolete port type
 typedef hamlib_port_t_deprecated port_t_deprecated;
+
+//! Short type name of the hamlib_port structure.
 typedef hamlib_port_t port_t;
 #endif
 
-// Macros for app access to hamlib_port_t data
+///@{
+/// Macro for application access to #hamlib_port_t data for this port type.
 #define HAMLIB_RIGPORT(r) ((hamlib_port_t *)rig_data_pointer((r), RIG_PTRX_RIGPORT))
 #define HAMLIB_PTTPORT(r) ((hamlib_port_t *)rig_data_pointer((r), RIG_PTRX_PTTPORT))
 #define HAMLIB_DCDPORT(r) ((hamlib_port_t *)rig_data_pointer((r), RIG_PTRX_DCDPORT))
 #define HAMLIB_AMPPORT(a) ((hamlib_port_t *)amp_data_pointer((a), RIG_PTRX_AMPPORT))
 #define HAMLIB_ROTPORT(r) ((hamlib_port_t *)rot_data_pointer((r), RIG_PTRX_ROTPORT))
 #define HAMLIB_ROTPORT2(r) ((hamlib_port_t *)rot_data_pointer((r), RIG_PTRX_ROTPORT2))
+///@}
 
 __END_DECLS
 
 #endif /* _HL_PORT_H */
+
+/** @} */

include/hamlib/rig.h

@@ -668,11 +668,11 @@ typedef enum dcd_e {
 
 
 /**
- * \brief DCD type
+ * \brief DCD (Data Carrier Detect) type
  *
  * \sa rig_get_dcd()
  */
-typedef enum {
+typedef enum dcd_type_e {
     RIG_DCD_NONE = 0,   /*!< No DCD available */
     RIG_DCD_RIG,        /*!< Rig has DCD status support, i.e. rig has get_dcd cap */
     RIG_DCD_SERIAL_DSR, /*!< DCD status from serial DSR signal */
@@ -697,11 +697,13 @@ typedef enum {
 
 
 /**
- * \brief PTT type
+ * \brief PTT (Push To Talk) type
+ *
+ * The method used to activate the transmitter of a radio.
  *
  * \sa rig_get_ptt()
  */
-typedef enum {
+typedef enum ptt_type_e {
     RIG_PTT_NONE = 0,       /*!< No PTT available */
     RIG_PTT_RIG,            /*!< Legacy PTT (CAT PTT) */
     RIG_PTT_SERIAL_DTR,     /*!< PTT control through serial DTR signal */