uip-ds6-nbr: add doxygen comments (and re-order some functions)

os/net/ipv6/uip-ds6-nbr.c

@@ -65,12 +65,39 @@
 #define LOG_LEVEL LOG_LEVEL_IPV6
 
 #if UIP_DS6_NBR_MULTI_IPV6_ADDRS
+/**
+ * Add nbr to the list in nbr_entry. In other words, this function associates an
+ * IPv6 address in nbr with a link-layer address in nbr_entry.
+ * \param nbr the neighbor cache entry for an IPv6 address
+ * \param nbr_entry the nbr_table entry for an link-layer address
+ */
 static void add_uip_ds6_nbr_to_nbr_entry(uip_ds6_nbr_t *nbr,
                                          uip_ds6_nbr_entry_t *nbr_entry);
+
+/**
+ * Remove nbr from the list of the corresponding nbr_entry
+ * \param nbr a neighbor cache entry (nbr) to be removed
+ */
 static void remove_uip_ds6_nbr_from_nbr_entry(uip_ds6_nbr_t *nbr);
+
+/**
+ * Remove nbr_etnry from nbr_table
+ * \param nbr_entry a nbr_table entry (nbr_entry) to be removed
+ */
 static void remove_nbr_entry(uip_ds6_nbr_entry_t *nbr_entry);
+
+/**
+ * Free memory for a specified neighbor cache entry
+ * \param nbr a neighbor cache entry to be freed
+ */
 static void free_uip_ds6_nbr(uip_ds6_nbr_t *nbr);
+
+/**
+ * Callback function called when a nbr_table entry is removed
+ * \param nbr_entry a nbr_entry to be removed
+ */
 static void callback_nbr_entry_removal(uip_ds6_nbr_entry_t *nbr_entry);
+
 NBR_TABLE(uip_ds6_nbr_entry_t, uip_ds6_nbr_entries);
 MEMB(uip_ds6_nbr_memb, uip_ds6_nbr_t, UIP_DS6_NBR_MAX_NEIGHBOR_CACHES);
 #else

os/net/ipv6/uip-ds6-nbr.h

@@ -67,27 +67,33 @@
 #define  NBR_DELAY 3
 #define  NBR_PROBE 4
 
+/** \brief Set non-zero (1) to enable multiple IPv6 addresses to be
+ * associated with a link-layer address */
 #ifdef UIP_DS6_NBR_CONF_MULTI_IPV6_ADDRS
 #define UIP_DS6_NBR_MULTI_IPV6_ADDRS UIP_DS6_NBR_CONF_MULTI_IPV6_ADDRS
 #else
 #define UIP_DS6_NBR_MULTI_IPV6_ADDRS 0
 #endif /* UIP_DS6_NBR_CONF_MULTI_IPV6_ADDRS */
 
+/** \brief Set the maximum number of neighbor cache entries */
 #ifdef UIP_DS6_NBR_CONF_MAX_NEIGHBOR_CACHES
 #define UIP_DS6_NBR_MAX_NEIGHBOR_CACHES UIP_DS6_NBR_CONF_MAX_NEIGHBOR_CACHES
 #else
-#define UIP_DS6_NBR_MAX_NEIGHBOR_CACHES NBR_TABLE_MAX_NEIGHBORS
+#define UIP_DS6_NBR_MAX_NEIGHBOR_CACHES \
+  (NBR_TABLE_MAX_NEIGHBORS * UIP_DS6_NBR_MAX_6ADDRS_PER_NBR)
 #endif /* UIP_DS6_NBR_CONF_MAX_NEIGHBOR_CACHES */
 
-
 #if UIP_DS6_NBR_MULTI_IPV6_ADDRS
-/** \brief An nbr_table entry for neighbor caches */
+/** \brief nbr_table entry when UIP_DS6_NBR_MULTI_IPV6_ADDRS is
+ * enabled. uip_ds6_nbrs is a list of uip_ds6_nbr_t objects */
 typedef struct {
   LIST_STRUCT(uip_ds6_nbrs);
 } uip_ds6_nbr_entry_t;
 #endif /* UIP_DS6_NBR_MULTI_IPV6_ADDRS */
 
-/** \brief An entry in the nbr cache */
+/** \brief The default nbr_table entry (when
+ * UIP_DS6_NBR_MULTI_IPV6_ADDRS is disabled), that implements nbr
+ * cache */
 typedef struct uip_ds6_nbr {
 #if UIP_DS6_NBR_MULTI_IPV6_ADDRS
   struct uip_ds6_nbr *next;
@@ -109,25 +115,119 @@ typedef struct uip_ds6_nbr {
 
 void uip_ds6_neighbors_init(void);
 
-/** \brief Neighbor Cache basic routines */
+/**
+ * Add a neighbor cache for a specified IPv6 address, which is
+ *  associated with a specified link-layer address
+ * \param ipaddr IPv6 address of a neighbor to add
+ * \param lladdr Link-layer address to associate with ipaddr
+ * \param isrouter Set 1 if the neighbor is a router
+ * \param state Set the initial neighbor cache state (e.g.,
+ * NBR_INCOMPLETE)
+ * \param reason Set a reason of the addition (e.g.,
+ * NBR_TABLE_REASON_RPL_DIO)
+ * \param data Set data associated with the nbr cache
+ * \return the address of a newly added nbr cache on success, NULL on
+ * failure
+*/
 uip_ds6_nbr_t *uip_ds6_nbr_add(const uip_ipaddr_t *ipaddr,
                                const uip_lladdr_t *lladdr,
                                uint8_t isrouter, uint8_t state,
                                nbr_table_reason_t reason, void *data);
+
+/**
+ * Remove a neighbor cache
+ * \param nbr the address of a neighbor cache to remove
+ * \return 1 on success, 0 on failure (nothing was removed)
+ */
 int uip_ds6_nbr_rm(uip_ds6_nbr_t *nbr);
+
+/**
+ * Get the link-layer address associated with a specified nbr cache
+ * \param nbr the address of a neighbor cache
+ * \return pointer to the link-layer address on success, NULL on failure
+ */
 const uip_lladdr_t *uip_ds6_nbr_get_ll(const uip_ds6_nbr_t *nbr);
-int uip_ds6_nbr_update_ll(uip_ds6_nbr_t **nbr, const uip_lladdr_t *new_ll_addr);
+
-const uip_ipaddr_t *uip_ds6_nbr_get_ipaddr(const uip_ds6_nbr_t *nbr);
+/**
-uip_ds6_nbr_t *uip_ds6_nbr_lookup(const uip_ipaddr_t *ipaddr);
+ * Get the link-layer address associated with a specified IPv6 address
-uip_ds6_nbr_t *uip_ds6_nbr_ll_lookup(const uip_lladdr_t *lladdr);
+ * \param ipaddr an IPv6 address used as a search key
-uip_ipaddr_t *uip_ds6_nbr_ipaddr_from_lladdr(const uip_lladdr_t *lladdr);
+ * \return the pointer to the link-layer address on success, NULL on failure
+ */
 const uip_lladdr_t *uip_ds6_nbr_lladdr_from_ipaddr(const uip_ipaddr_t *ipaddr);
-void uip_ds6_link_callback(int status, int numtx);
+
-void uip_ds6_neighbor_periodic(void);
+/**
+ * Update the link-layer address associated with an  IPv6 address
+ * \param nbr the double pointer to a neighbor cache which has the
+ * target IPv6 address
+ * \param new_ll_addr the new link-layer address of the IPv6 address
+ * return 0 on success, -1 on failure
+ */
+int uip_ds6_nbr_update_ll(uip_ds6_nbr_t **nbr, const uip_lladdr_t *new_ll_addr);
+
+/**
+ * Get an IPv6 address of a neighbor cache
+ * \param nbr the pointer to a neighbor cache
+ * \return the pointer to an IPv6 address associated with the neighbor cache
+ * \note This returns the first IPv6 address found in the neighbor
+ * cache when UIP_DS6_NBR_MULTI_IPV6_ADDRS is enabled
+ */
+const uip_ipaddr_t *uip_ds6_nbr_get_ipaddr(const uip_ds6_nbr_t *nbr);
+
+/**
+ * Get an IPv6 address associated with a specified link-layer address
+ * \param lladdr a link-layer address used as a search key
+ * \return the pointer to an IPv6 address associated with the neighbor cache
+ * \note This returns the first IPv6 address found in the neighbor
+ * cache when UIP_DS6_NBR_MULTI_IPV6_ADDRS is enabled
+ */
+uip_ipaddr_t *uip_ds6_nbr_ipaddr_from_lladdr(const uip_lladdr_t *lladdr);
+
+/**
+ * Get the neighbor cache associated with a specified IPv6 address
+ * \param ipaddr an IPv6 address used as a search key
+ * \return the pointer to a neighbor cache on success, NULL on failure
+ */
+uip_ds6_nbr_t *uip_ds6_nbr_lookup(const uip_ipaddr_t *ipaddr);
+
+/**
+ * Get the neighbor cache associated with a specified link-layer address
+ * \param lladdr a link-layer address used as a search key
+ * \return the pointer to a neighbor cache on success, NULL on failure
+ */
+uip_ds6_nbr_t *uip_ds6_nbr_ll_lookup(const uip_lladdr_t *lladdr);
+
+/**
+ * Return the number of neighbor caches
+ * \return the number of neighbor caches in use
+ */
 int uip_ds6_nbr_num(void);
+
+/**
+ * Get the first neighbor cache in nbr_table
+ * \return the pointer to the first neighbor cache entry
+ */
 uip_ds6_nbr_t *uip_ds6_nbr_head(void);
+
+/**
+ * Get the next neighbor cache of a specified one
+ * \param nbr the pointer to a neighbor cache
+ * \return the pointer to the next one on success, NULL on failure
+ */
 uip_ds6_nbr_t *uip_ds6_nbr_next(uip_ds6_nbr_t *nbr);
 
+/**
+ * The callback function to update link-layer stats in a neighbor
+ * cache
+ * \param status MAC return value defined in mac.h
+ * \param numtx the number of transmissions happened for a packet
+ */
+void uip_ds6_link_callback(int status, int numtx);
+
+/**
+ * The housekeeping function called periodically
+ */
+void uip_ds6_neighbor_periodic(void);
+
 #if UIP_ND6_SEND_NS
 /**
  * \brief Refresh the reachable state of a neighbor. This function