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

doc/doxygen/lwip.Doxyfile

@@ -2080,6 +2080,7 @@ PREDEFINED             = NO_SYS=0 \
                          LWIP_IGMP=1 \
                          LWIP_TCP=1 \
                          LWIP_SNMP=1 \
+                         SNMP_USE_RAW=1 \
                          MEMP_OVERFLOW_CHECK=0 \
                          MEMP_SANITY_CHECK=1 \
                          LWIP_ARP=1 \

doc/doxygen/main_page.h

@@ -6,6 +6,12 @@
  * @defgroup threadsafe_api Thread-safe APIs
  * Thread-safe APIs, blocking functions. More overhead, but can be called
  * from any thread except TCPIP thread.
+ * 
+ * @defgroup infrastructure Infrastructure
+ * 
+ * @defgroup addons Addons
+ * 
+ * @defgroup apps Applications
  */
 
 /*! \mainpage lwIP Documentation

doc/doxygen/ppp.h

@@ -1,4 +1,5 @@
 /**
  * @defgroup ppp PPP
+ * @ingroup addons
  * @verbinclude "ppp.txt"
  */

src/apps/httpd/httpd.c

@@ -36,7 +36,11 @@
  *
  */
 
-/* This httpd supports for a
+/**
+ * @defgroup httpd HTTP server
+ * @ingroup apps
+ *
+ * This httpd supports for a
  * rudimentary server-side-include facility which will replace tags of the form
  * <!--#tag--> in any file whose extension is .shtml, .shtm or .ssi with
  * strings provided by an include handler whose pointer is provided to the
@@ -2611,6 +2615,7 @@ http_accept(void *arg, struct tcp_pcb *pcb, err_t err)
 }
 
 /**
+ * @ingroup httpd
  * Initialize the httpd: set up a listening PCB and bind it to the defined port
  */
 void

src/apps/netbiosns/netbiosns.c

@@ -1,6 +1,11 @@
 /**
  * @file
  * NetBIOS name service responder
+ */
+
+/**
+ * @defgroup netbiosns NETBIOS responder
+ * @ingroup apps
  *
  * This is an example implementation of a NetBIOS name server.
  * It responds to name queries for a configurable name.
@@ -308,6 +313,10 @@ netbiosns_recv(void *arg, struct udp_pcb *upcb, struct pbuf *p, const ip_addr_t
   }
 }
 
+/**
+ * @ingroup netbiosns 
+ * Init netbios responder
+ */
 void
 netbiosns_init(void)
 {
@@ -325,7 +334,10 @@ netbiosns_init(void)
 }
 
 #ifndef NETBIOS_LWIP_NAME
-/* ATTENTION: the hostname must be <= 15 characters! */
+/**
+ * @ingroup netbiosns 
+ * Set netbios name. ATTENTION: the hostname must be less than 15 characters!
+ */
 void
 netbiosns_set_name(const char* hostname)
 {
@@ -338,6 +350,10 @@ netbiosns_set_name(const char* hostname)
 }
 #endif
 
+/**
+ * @ingroup netbiosns 
+ * Stop netbios responder
+ */
 void
 netbiosns_stop(void)
 {

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)
 {

src/apps/sntp/sntp.c

@@ -1,17 +1,6 @@
 /**
  * @file
  * SNTP client module
- *
- * This is simple "SNTP" client for the lwIP raw API.
- * It is a minimal implementation of SNTPv4 as specified in RFC 4330.
- *
- * For a list of some public NTP servers, see this link :
- * http://support.ntp.org/bin/view/Servers/NTPPoolServers
- *
- * @todo:
- * - set/change servers at runtime
- * - complete SNTP_CHECK_RESPONSE checks 3 and 4
- * - support broadcast/multicast mode?
  */
 
 /*
@@ -45,6 +34,22 @@
  * Author: Frédéric Bernon, Simon Goldschmidt
  */
 
+
+/**
+ * @defgroup sntp SNTP
+ * @ingroup apps
+ *
+ * This is simple "SNTP" client for the lwIP raw API.
+ * It is a minimal implementation of SNTPv4 as specified in RFC 4330.
+ *
+ * For a list of some public NTP servers, see this link :
+ * http://support.ntp.org/bin/view/Servers/NTPPoolServers
+ *
+ * @todo:
+ * - set/change servers at runtime
+ * - complete SNTP_CHECK_RESPONSE checks 3 and 4
+ */
+
 #include "lwip/apps/sntp.h"
 
 #include "lwip/opt.h"
@@ -523,6 +528,7 @@ sntp_request(void *arg)
 }
 
 /**
+ * @ingroup sntp
  * Initialize this module.
  * Send out request instantly or after SNTP_STARTUP_DELAY(_FUNC).
  */
@@ -559,6 +565,7 @@ sntp_init(void)
 }
 
 /**
+ * @ingroup sntp
  * Stop this module.
  */
 void
@@ -572,6 +579,7 @@ sntp_stop(void)
 }
 
 /**
+ * @ingroup sntp
  * Get enabled state.
  */
 u8_t sntp_enabled(void)
@@ -580,6 +588,7 @@ u8_t sntp_enabled(void)
 }
 
 /**
+ * @ingroup sntp
  * Sets the operating mode.
  * @param operating_mode one of the available operating modes
  */
@@ -592,6 +601,7 @@ sntp_setoperatingmode(u8_t operating_mode)
 }
 
 /**
+ * @ingroup sntp
  * Gets the operating mode.
  */
 u8_t
@@ -616,6 +626,7 @@ sntp_servermode_dhcp(int set_servers_from_dhcp)
 #endif /* SNTP_GET_SERVERS_FROM_DHCP */
 
 /**
+ * @ingroup sntp
  * Initialize one of the NTP servers by IP address
  *
  * @param idx the index of the NTP server to set must be < SNTP_MAX_SERVERS
@@ -664,6 +675,7 @@ dhcp_set_ntp_servers(u8_t num, const ip4_addr_t *server)
 #endif /* LWIP_DHCP && SNTP_GET_SERVERS_FROM_DHCP */
 
 /**
+ * @ingroup sntp
  * Obtain one of the currently configured by IP address (or DHCP) NTP servers
  *
  * @param idx the index of the NTP server

src/core/ip.c

@@ -44,6 +44,7 @@
  * @ingroup callbackstyle_api
  * 
  * @defgroup ipaddr IP address handling
+ * @ingroup infrastructure
  * 
  * @defgroup ip4addr IPv4 only
  * @ingroup ipaddr

src/core/memp.c

@@ -40,6 +40,8 @@
 
 /**
  * @defgroup mempool Memory pools
+ * @ingroup infrastructure
+ * Custom memory pools
  */
 
 #include "lwip/opt.h"

src/core/pbuf.c

@@ -5,6 +5,7 @@
 
 /**
  * @defgroup pbuf Payload buffers (PBUF)
+ * @ingroup infrastructure
  *
  * Packets are built from the pbuf data structure. It supports dynamic
  * memory allocation for packet contents or can reference externally

src/include/lwip/apps/netbiosns.h

@@ -34,13 +34,10 @@
 
 #include "lwip/apps/netbiosns_opts.h"
 
-/** Init netbios responder */
 void netbiosns_init(void);
 #ifndef NETBIOS_LWIP_NAME
-/** Set netbios name. ATTENTION: the hostname must be <= 15 characters! */
 void netbiosns_set_name(const char* hostname);
 #endif
-/** Stop netbios responder */
 void netbiosns_stop(void);
 
 #endif /* LWIP_HDR_APPS_NETBIOS_H */

src/include/lwip/apps/snmp.h

@@ -69,7 +69,10 @@ struct snmp_varbind
   void *value;
 };
 
-/** Agent setup, start listening to port 161. */
+/**
+ * @ingroup snmp_core
+ * Agent setup, start listening to port 161.
+ */
 void snmp_init(void);
 void snmp_set_mibs(const struct snmp_mib **mibs, u8_t num_mibs);