Documentation review with Simon, minor changes

doc/doxygen/lwip.Doxyfile

@@ -614,7 +614,7 @@ STRICT_PROTO_MATCHING  = NO
 # list. This list is created by putting \todo commands in the documentation.
 # The default value is: YES.
 
-GENERATE_TODOLIST      = YES
+GENERATE_TODOLIST      = NO
 
 # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
 # list. This list is created by putting \test commands in the documentation.

src/api/api_lib.c

@@ -52,10 +52,6 @@
  * @defgroup netconn_udp UDP only
  * @ingroup netconn
  * UDP only functions
- * 
- * @defgroup netconn_dns DNS
- * @ingroup netconn
- * DNS lookup
  */
 
 /* This is the part of the API that is linked with
@@ -204,7 +200,6 @@ netconn_delete(struct netconn *conn)
 }
 
 /**
- * @ingroup netconn_tcp
  * Get the local or remote IP address and port of a netconn.
  * For RAW netconns, this returns the protocol instead of a port!
  *
@@ -893,7 +888,7 @@ netconn_join_leave_group(struct netconn *conn,
 
 #if LWIP_DNS
 /**
- * @ingroup netconn_dns
+ * @ingroup netconn_common
  * Execute a DNS query, only one IP address is returned
  *
  * @param name a string representation of the DNS host name to query

src/api/netbuf.c

@@ -40,7 +40,9 @@
  * @defgroup netbuf Network buffers
  * @ingroup netconn
  * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally
- * to avoid copying data around.
+ * to avoid copying data around.\n
+ * Buffers must not be shared accross multiple threads, all functions except
+ * netbuf_new() and netbuf_delete() are not thread-safe.
  */
 
 #include "lwip/opt.h"

src/apps/lwiperf/lwiperf.c

@@ -1,6 +1,11 @@
 /**
  * @file
  * LWIP iperf server implementation
+ */
+
+/**
+ * @defgroup iperf Iperf server
+ * @ingroup apps
  *
  * This is simple "Iperf" server to check your bandwith using Iperf on a PC as client.
  * It is currently a minimal implementation providing an IPv4 TCP server only.
@@ -562,7 +567,9 @@ lwiperf_tcp_accept(void *arg, struct tcp_pcb *newpcb, err_t err)
   return ERR_OK;
 }
 
-/** Start a TCP iperf server on the default TCP port (5001) and listen for
+/** 
+ * @ingroup iperf
+ * Start a TCP iperf server on the default TCP port (5001) and listen for
  * incoming connections from iperf clients.
  *
  * @returns a connection handle that can be used to abort the server
@@ -575,7 +582,9 @@ lwiperf_start_tcp_server_default(lwiperf_report_fn report_fn, void* report_arg)
     report_fn, report_arg);
 }
 
-/** Start a TCP iperf server on a specific IP address and port and listen for
+/**
+ * @ingroup iperf
+ * Start a TCP iperf server on a specific IP address and port and listen for
  * incoming connections from iperf clients.
  *
  * @returns a connection handle that can be used to abort the server
@@ -626,7 +635,10 @@ lwiperf_start_tcp_server(const ip_addr_t* local_addr, u16_t local_port,
   return s;
 }
 
-/** Abort an iperf session (handle returned by lwiperf_start_tcp_server*()) */
+/**
+ * @ingroup iperf
+ * Abort an iperf session (handle returned by lwiperf_start_tcp_server*())
+ */
 void
 lwiperf_abort(void* lwiperf_session)
 {

src/apps/snmp/snmp_core.c

@@ -36,6 +36,12 @@
 /**
  * @defgroup snmp SNMPv2c agent
  * @ingroup apps
+ * SNMPv2c compatible agent\n
+ * There is also a MIB compiler and a MIB viewer included in this project.\n
+ * The agent implements the most important MIB2 MIBs including IPv6 support
+ * (interfaces, UDP, TCP, SNMP, ICMP, SYSTEM). IP MIB is an older version
+ * whithout IPv6 statistics (TODO).\n
+ * Work on SNMPv3 has started, but is not finished. 
  * 
  * @defgroup snmp_core Core
  * @ingroup snmp

src/core/pbuf.c

@@ -4,7 +4,7 @@
  */
 
 /**
- * @defgroup pbuf Payload buffers (PBUF)
+ * @defgroup pbuf Packet buffers (PBUF)
  * @ingroup infrastructure
  *
  * Packets are built from the pbuf data structure. It supports dynamic

src/core/timeouts.c

@@ -292,7 +292,9 @@ sys_untimeout(sys_timeout_handler handler, void *arg)
   return;
 }
 
-/** Handle timeouts for NO_SYS==1 (i.e. without using
+/**
+ * @ingroup lwip
+ * Handle timeouts for NO_SYS==1 (i.e. without using
  * tcpip_thread/sys_timeouts_mbox_fetch(). Uses sys_now() to call timeout
  * handler functions when timeouts expire.
  *

src/include/lwip/api.h

@@ -275,6 +275,7 @@ err_t   netconn_bind(struct netconn *conn, const ip_addr_t *addr, u16_t port);
 err_t   netconn_connect(struct netconn *conn, const ip_addr_t *addr, u16_t port);
 err_t   netconn_disconnect (struct netconn *conn);
 err_t   netconn_listen_with_backlog(struct netconn *conn, u8_t backlog);
+/** @ingroup netconn_tcp */
 #define netconn_listen(conn) netconn_listen_with_backlog(conn, TCP_DEFAULT_LISTEN_BACKLOG)
 err_t   netconn_accept(struct netconn *conn, struct netconn **new_conn);
 err_t   netconn_recv(struct netconn *conn, struct netbuf **new_buf);

src/include/lwip/pbuf.h

@@ -114,8 +114,7 @@ typedef enum {
 /** indicates this pbuf includes a TCP FIN flag */
 #define PBUF_FLAG_TCP_FIN   0x20U
 
-/** Main payload buffer struct
+/** Main packet buffer struct */
- */
 struct pbuf {
   /** next pbuf in singly linked pbuf chain */
   struct pbuf *next;

src/include/lwip/sys.h

@@ -39,14 +39,17 @@
  * @ingroup infrastructure
  * @verbinclude "sys_arch.txt"
  *
- * @defgroup sys_sem Semaphores
+ * @defgroup sys_os OS abstraction layer
  * @ingroup sys_layer
  *
+ * @defgroup sys_sem Semaphores
+ * @ingroup sys_os
+ *
  * @defgroup sys_mutex Mutexes
- * @ingroup sys_layer
+ * @ingroup sys_os
  *
  * @defgroup sys_mbox Mailboxes
- * @ingroup sys_layer
+ * @ingroup sys_os
  *
  * @defgroup sys_time Time
  * @ingroup sys_layer
@@ -55,7 +58,7 @@
  * @ingroup sys_layer
  *
  * @defgroup sys_thread Threads
- * @ingroup sys_layer
+ * @ingroup sys_os
  */
 
 #ifndef LWIP_HDR_SYS_H
@@ -359,7 +362,6 @@ void sys_init(void);
 
 #ifndef sys_jiffies
 /**
- * @ingroup sys_time
  * Ticks/jiffies since power up.
  */
 u32_t sys_jiffies(void);