From eae41298634e34f57483bdf9fbf7e7d9ca2e04e6 Mon Sep 17 00:00:00 2001
From: Dirk Ziegelmeier <dirk@ziegelmeier.net>
Date: Thu, 9 Feb 2017 19:39:07 +0100
Subject: [PATCH] Documentation updates related to Joel's if_api changes

---
 src/api/if_api.c         | 19 +++++++++++++++++++
 src/core/netif.c         |  4 ++--
 src/include/lwip/netif.h |  3 ++-
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/src/api/if_api.c b/src/api/if_api.c
index 02ee21d1..6283b4a2 100644
--- a/src/api/if_api.c
+++ b/src/api/if_api.c
@@ -3,6 +3,9 @@
  * Interface Identification APIs from:
  *              RFC 3493: Basic Socket Interface Extensions for IPv6
  *                  Section 4: Interface Identification
+ * 
+ * @defgroup if_api Interface Identification API
+ * @ingroup socket
  */
 
 /*
@@ -43,6 +46,15 @@
 #include "lwip/if_api.h"
 #include "lwip/netifapi.h"
 
+/**
+ * @ingroup if_api
+ * Maps an interface index to its corresponding name.
+ * @param ifindex interface index 
+ * @param ifname shall point to a buffer of at least {IF_NAMESIZE} bytes
+ * @return If ifindex is an interface index, then the function shall return the
+ * value supplied in ifname, which points to a buffer now containing the interface name.
+ * Otherwise, the function shall return a NULL pointer.
+ */
 char *
 lwip_if_indextoname(unsigned int ifindex, char *ifname)
 {
@@ -63,6 +75,13 @@ lwip_if_indextoname(unsigned int ifindex, char *ifname)
   return NULL;
 }
 
+/**
+ * @ingroup if_api
+ * Returs the interface index corresponding to name ifname.
+ * @param ifname Interface name
+ * @return The corresponding index if ifname is the name of an interface;
+ * otherwise, zero.
+ */
 unsigned int
 lwip_if_nametoindex(const char *ifname)
 {
diff --git a/src/core/netif.c b/src/core/netif.c
index 3d039b05..baac4dc5 100644
--- a/src/core/netif.c
+++ b/src/core/netif.c
@@ -1298,7 +1298,7 @@ netif_null_output_ip6(struct netif *netif, struct pbuf *p, const ip6_addr_t *ipa
 #endif /* LWIP_IPV6 */
 
 /**
-* @ingroup netif_if
+* @ingroup netif
 * Return the interface index for the netif with name
 * or 0 (invalid interface) if not found/on error
 *
@@ -1316,7 +1316,7 @@ netif_name_to_index(const char *name)
 }
 
 /**
-* @ingroup netif_if
+* @ingroup netif
 * Return the interface name for the netif matching index
 * or NULL if not found/on error
 *
diff --git a/src/include/lwip/netif.h b/src/include/lwip/netif.h
index aff4937d..7241b42a 100644
--- a/src/include/lwip/netif.h
+++ b/src/include/lwip/netif.h
@@ -312,7 +312,8 @@ struct netif {
   u8_t flags;
   /** descriptive abbreviation */
   char name[2];
-  /** number of this interface */
+  /** number of this interface. Used for @ref if_api and @ref netifapi_netif, 
+   * as well as for IPv6 zones */
   u8_t num;
 #if LWIP_IPV6_AUTOCONFIG
   /** is this netif enabled for IPv6 autoconfiguration */