Document apps in doxygen module style, create more top-level categories to structure documentation

src/apps/snmp/snmp_core.c

@@ -33,6 +33,17 @@
  *         Martin Hentschel <info@cl-soft.de>
 */
 
+/**
+ * @defgroup snmp SNMPv2c agent
+ * @ingroup apps
+ * 
+ * @defgroup snmp_core Core
+ * @ingroup snmp
+ * 
+ * @defgroup snmp_traps Traps
+ * @ingroup snmp
+ */
+
 #include "lwip/apps/snmp_opts.h"
 
 #if LWIP_SNMP /* don't build if not configured for use in lwipopts.h */
@@ -72,6 +83,7 @@ static u8_t snmp_num_mibs                          = 0;
 static struct snmp_mib const * const *snmp_mibs = default_mibs;
 
 /**
+ * @ingroup snmp_core
  * Sets the MIBs to use.
  * Example: call snmp_set_mibs() as follows:
  * static const struct snmp_mib *my_snmp_mibs[] = {
@@ -90,18 +102,19 @@ snmp_set_mibs(const struct snmp_mib **mibs, u8_t num_mibs)
 }
 
 /**
-* 'device enterprise oid' is used for 'device OID' field in trap PDU's (for identification of generating device)
-* as well as for value returned by MIB-2 'sysObjectID' field (if internal MIB2 implementation is used).
-* The 'device enterprise oid' shall point to an OID located under 'private-enterprises' branch (1.3.6.1.4.1.XXX). If a vendor
-* wants to provide a custom object there, he has to get its own enterprise oid from IANA (http://www.iana.org). It
-* is not allowed to use LWIP enterprise ID!
-* In order to identify a specific device it is recommended to create a dedicated OID for each device type under its own 
-* enterprise oid.
-* e.g.
-* device a > 1.3.6.1.4.1.XXX(ent-oid).1(devices).1(device a)
-* device b > 1.3.6.1.4.1.XXX(ent-oid).1(devices).2(device b)
-* for more details see description of 'sysObjectID' field in RFC1213-MIB
-*/
+ * @ingroup snmp_core
+ * 'device enterprise oid' is used for 'device OID' field in trap PDU's (for identification of generating device)
+ * as well as for value returned by MIB-2 'sysObjectID' field (if internal MIB2 implementation is used).
+ * The 'device enterprise oid' shall point to an OID located under 'private-enterprises' branch (1.3.6.1.4.1.XXX). If a vendor
+ * wants to provide a custom object there, he has to get its own enterprise oid from IANA (http://www.iana.org). It
+ * is not allowed to use LWIP enterprise ID!
+ * In order to identify a specific device it is recommended to create a dedicated OID for each device type under its own 
+ * enterprise oid.
+ * e.g.
+ * device a > 1.3.6.1.4.1.XXX(ent-oid).1(devices).1(device a)
+ * device b > 1.3.6.1.4.1.XXX(ent-oid).1(devices).2(device b)
+ * for more details see description of 'sysObjectID' field in RFC1213-MIB
+ */
 void snmp_set_device_enterprise_oid(const struct snmp_obj_id* device_enterprise_oid)
 {
   if (device_enterprise_oid == NULL) {
@@ -111,7 +124,10 @@ void snmp_set_device_enterprise_oid(const struct snmp_obj_id* device_enterprise_
   }
 }
 
-/** Get 'device enterprise oid' */
+/**
+ * @ingroup snmp_core
+ * Get 'device enterprise oid' 
+ */
 const struct snmp_obj_id* snmp_get_device_enterprise_oid(void)
 {
   return snmp_device_enterprise_oid;

src/apps/snmp/snmp_msg.c

@@ -67,6 +67,7 @@ snmp_write_callback_fct snmp_write_callback     = NULL;
 void*                   snmp_write_callback_arg = NULL;
 
 /**
+ * @ingroup snmp_core
  * Returns current SNMP community string.
  * @return current SNMP community string
  */
@@ -77,6 +78,7 @@ snmp_get_community(void)
 }
 
 /**
+ * @ingroup snmp_core
  * Sets SNMP community string.
  * The string itself (its storage) must be valid throughout the whole life of
  * program (or until it is changed to sth else).
@@ -91,6 +93,7 @@ snmp_set_community(const char * const community)
 }
 
 /**
+ * @ingroup snmp_core
  * Returns current SNMP write-access community string.
  * @return current SNMP write-access community string
  */
@@ -101,6 +104,7 @@ snmp_get_community_write(void)
 }
 
 /**
+ * @ingroup snmp_traps
  * Returns current SNMP community string used for sending traps.
  * @return current SNMP community string used for sending traps
  */
@@ -111,6 +115,7 @@ snmp_get_community_trap(void)
 }
 
 /**
+ * @ingroup snmp_core
  * Sets SNMP community string for write-access.
  * The string itself (its storage) must be valid throughout the whole life of
  * program (or until it is changed to sth else).
@@ -125,6 +130,7 @@ snmp_set_community_write(const char * const community)
 }
 
 /**
+ * @ingroup snmp_traps
  * Sets SNMP community string used for sending traps.
  * The string itself (its storage) must be valid throughout the whole life of
  * program (or until it is changed to sth else).
@@ -138,6 +144,10 @@ snmp_set_community_trap(const char * const community)
   snmp_community_trap = community;
 }
 
+/**
+ * @ingroup snmp_core
+ * Callback fired on every successful write access
+ */
 void 
 snmp_set_write_callback(snmp_write_callback_fct write_callback, void* callback_arg)
 {

src/apps/snmp/snmp_raw.c

@@ -78,6 +78,7 @@ snmp_get_local_ip_for_dst(void* handle, const ip_addr_t *dst, ip_addr_t *result)
 }
 
 /**
+ * @ingroup snmp_core
  * Starts SNMP Agent.
  * Allocates UDP pcb and binds it to IP_ADDR_ANY port 161.
  */

src/apps/snmp/snmp_traps.c

@@ -98,6 +98,7 @@ static struct snmp_trap_dst trap_dst[SNMP_TRAP_DESTINATIONS];
 static u8_t snmp_auth_traps_enabled = 0;
 
 /**
+ * @ingroup snmp_traps
  * Sets enable switch for this trap destination.
  * @param dst_idx index in 0 .. SNMP_TRAP_DESTINATIONS-1
  * @param enable switch if 0 destination is disabled >0 enabled.
@@ -111,6 +112,7 @@ snmp_trap_dst_enable(u8_t dst_idx, u8_t enable)
 }
 
 /**
+ * @ingroup snmp_traps
  * Sets IPv4 address for this trap destination.
  * @param dst_idx index in 0 .. SNMP_TRAP_DESTINATIONS-1
  * @param dst IPv4 address in host order.
@@ -123,14 +125,20 @@ snmp_trap_dst_ip_set(u8_t dst_idx, const ip_addr_t *dst)
   }
 }
 
-/** Enable/disable authentication traps */
+/**
+ * @ingroup snmp_traps
+ * Enable/disable authentication traps
+ */
 void
 snmp_set_auth_traps_enabled(u8_t enable)
 {
   snmp_auth_traps_enabled = enable;
 }
 
-/** Get authentication traps enabled state */
+/**
+ * @ingroup snmp_traps
+ * Get authentication traps enabled state
+ */
 u8_t
 snmp_get_auth_traps_enabled(void)
 {
@@ -214,7 +222,10 @@ snmp_send_trap(const struct snmp_obj_id *device_enterprise_oid, s32_t generic_tr
   return err;
 }
 
-/** Send generic SNMP trap */
+/**
+ * @ingroup snmp_traps
+ *  Send generic SNMP trap
+ */
 err_t 
 snmp_send_trap_generic(s32_t generic_trap)
 {
@@ -222,21 +233,30 @@ snmp_send_trap_generic(s32_t generic_trap)
   return snmp_send_trap(&oid, generic_trap, 0, NULL);
 }
 
-/** Send specific SNMP trap with variable bindings */
+/**
+ *@ingroup snmp_traps
+ * Send specific SNMP trap with variable bindings
+ */
 err_t
 snmp_send_trap_specific(s32_t specific_trap, struct snmp_varbind *varbinds)
 {
   return snmp_send_trap(NULL, SNMP_GENTRAP_ENTERPRISE_SPECIFIC, specific_trap, varbinds);
 }
 
-/** Send coldstart trap */
+/**
+ * @ingroup snmp_traps
+ * Send coldstart trap
+ */
 void
 snmp_coldstart_trap(void)
 {
   snmp_send_trap_generic(SNMP_GENTRAP_COLDSTART);
 }
 
-/** Send authentication failure trap (used internally by agent) */
+/**
+ * @ingroup snmp_traps
+ * Send authentication failure trap (used internally by agent) 
+ */
 void
 snmp_authfail_trap(void)
 {