Tidy-up multicast documentation

* Create a doxygen group and add files to it, so that documents appear as modules rather than simply under files
* Document plenty of functions, macros, constants, data types which were previously undocumented
* Re-structure some doxygen comments to improve structure and readability

core/net/ipv6/multicast/roll-tm.c

@@ -29,18 +29,13 @@
  * This file is part of the Contiki operating system.
  */
 
+/**
+ * \addtogroup roll-tm
+ * @{
+ */
 /**
  * \file
- *         This file implements IPv6 MCAST forwarding according to the
+ *    Implementation of the ROLL TM multicast engine
- *         algorithm described in the "MCAST Forwarding Using Trickle"
- *         internet draft.
- *
- *         The current version of the draft can always be found in
- *         http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
- *
- *         This implementation is based on the draft version stored in
- *         ROLL_TM_VER
- *
  * \author
  *    George Oikonomou - <oikonomou@users.sourceforge.net>
  */
@@ -1440,6 +1435,9 @@ init()
   return;
 }
 /*---------------------------------------------------------------------------*/
+/**
+ * \brief The ROLL TM engine driver
+ */
 const struct uip_mcast6_driver roll_tm_driver = {
   "ROLL TM",
   init,
@@ -1447,3 +1445,4 @@ const struct uip_mcast6_driver roll_tm_driver = {
   in,
 };
 /*---------------------------------------------------------------------------*/
+/** @} */

core/net/ipv6/multicast/roll-tm.h

@@ -30,8 +30,13 @@
  */
 
 /**
- * \file
+ * \addtogroup uip6-multicast
- *         Header file for IPv6 multicast according to the algorithm in the
+ * @{
+ */
+/**
+ * \defgroup roll-tm ROLL Trickle Multicast
+ *
+ * IPv6 multicast according to the algorithm in the
  * "MCAST Forwarding Using Trickle" internet draft.
  *
  * The current version of the draft can always be found in
@@ -45,7 +50,11 @@
  * Due to very significant changes between draft versions 1 and 2,
  * MPL will be implemented as a separate engine and this file here
  * will provide legacy support for Draft v1.
- *
+ * @{
+ */
+/**
+ * \file
+ *    Header file for the implementation of the ROLL-TM multicast engine
  * \author
  *    George Oikonomou - <oikonomou@users.sourceforge.net>
  */
@@ -60,9 +69,9 @@
 /*---------------------------------------------------------------------------*/
 /* Protocol Constants */
 /*---------------------------------------------------------------------------*/
-#define ROLL_TM_VER                    1   /* Supported Draft Version */
+#define ROLL_TM_VER                    1   /**< Supported Draft Version */
-#define ROLL_TM_ICMP_CODE              0   /* ICMPv6 code field */
+#define ROLL_TM_ICMP_CODE              0   /**< ROLL TM ICMPv6 code field */
-#define ROLL_TM_IP_HOP_LIMIT        0xFF   /* Hop limit for ICMP messages */
+#define ROLL_TM_IP_HOP_LIMIT        0xFF   /**< Hop limit for ICMP messages */
 #define ROLL_TM_INFINITE_REDUNDANCY 0xFF
 #define ROLL_TM_DGRAM_OUT              0
 #define ROLL_TM_DGRAM_IN               1
@@ -153,7 +162,7 @@
 /*---------------------------------------------------------------------------*/
 /* Configuration */
 /*---------------------------------------------------------------------------*/
-/*
+/**
  * Number of Sliding Windows
  * In essence: How many unique sources of simultaneous multicast traffic do we
  * want to support for our lowpan
@@ -166,7 +175,7 @@
 #define ROLL_TM_WINS 2
 #endif
 /*---------------------------------------------------------------------------*/
-/*
+/**
  * Maximum Number of Buffered Multicast Messages
  * This buffer is shared across all Seed IDs, therefore a new very active Seed
  * may eventually occupy all slots. It would make little sense (if any) to
@@ -178,7 +187,7 @@
 #define ROLL_TM_BUFF_NUM 6
 #endif
 /*---------------------------------------------------------------------------*/
-/*
+/**
  * Use Short Seed IDs [short: 2, long: 16 (default)]
  * It can be argued that we should (and it would be easy to) support both at
  * the same time but the draft doesn't list this as a MUST so we opt for
@@ -190,7 +199,7 @@
 #define ROLL_TM_SHORT_SEEDS 0
 #endif
 /*---------------------------------------------------------------------------*/
-/*
+/**
  * Destination address for our ICMPv6 advertisements. The draft gives us a
  * choice between LL all-nodes or LL all-routers
  *
@@ -202,7 +211,7 @@
 #define ROLL_TM_DEST_ALL_NODES 0
 #endif
 /*---------------------------------------------------------------------------*/
-/*
+/**
  * M param for our outgoing messages
  * By default, we set the M bit (conservative). Define this as 0 to clear the
  * M bit in our outgoing messages (aggressive)
@@ -215,10 +224,21 @@
 /*---------------------------------------------------------------------------*/
 /* Stats datatype */
 /*---------------------------------------------------------------------------*/
+/**
+ * \brief Multicast stats extension for the ROLL TM engine
+ */
 struct roll_tm_stats {
+  /** Number of received ICMP datagrams */
   UIP_MCAST6_STATS_DATATYPE icmp_in;
+
+  /** Number of ICMP datagrams sent */
   UIP_MCAST6_STATS_DATATYPE icmp_out;
+
+  /** Number of malformed ICMP datagrams seen by us */
   UIP_MCAST6_STATS_DATATYPE icmp_bad;
 };
-
+/*---------------------------------------------------------------------------*/
 #endif /* ROLL_TM_H_ */
+/*---------------------------------------------------------------------------*/
+/** @} */
+/** @} */

core/net/ipv6/multicast/smrf.c

@@ -29,12 +29,14 @@
  * This file is part of the Contiki operating system.
  */
 
+/**
+ * \addtogroup smrf-multicast
+ * @{
+ */
 /**
  * \file
  *    This file implements 'Stateless Multicast RPL Forwarding' (SMRF)
  *
- *         It will only work in RPL networks in MOP 3 "Storing with Multicast"
- *
  * \author
  *    George Oikonomou - <oikonomou@users.sourceforge.net>
  */
@@ -199,6 +201,9 @@ out()
   return;
 }
 /*---------------------------------------------------------------------------*/
+/**
+ * \brief The SMRF engine driver
+ */
 const struct uip_mcast6_driver smrf_driver = {
   "SMRF",
   init,
@@ -206,3 +211,4 @@ const struct uip_mcast6_driver smrf_driver = {
   in,
 };
 /*---------------------------------------------------------------------------*/
+/** @} */

core/net/ipv6/multicast/smrf.h

@@ -29,9 +29,19 @@
  * This file is part of the Contiki operating system.
  */
 
+/**
+ * \addtogroup uip6-multicast
+ * @{
+ */
+/**
+ * \defgroup smrf-multicast 'Stateless Multicast RPL Forwarding' (SMRF)
+ *
+ * SMRF will only work in RPL networks in MOP 3 "Storing with Multicast"
+ * @{
+ */
 /**
  * \file
- *         Header file for 'Stateless Multicast RPL Forwarding' (SMRF)
+ *    Header file for the SMRF forwarding engine
  *
  * \author
  *    George Oikonomou - <oikonomou@users.sourceforge.net>
@@ -71,5 +81,8 @@ struct smrf_stats {
   uint16_t mcast_bad;
   uint16_t mcast_dropped;
 };
-
+/*---------------------------------------------------------------------------*/
 #endif /* SMRF_H_ */
+/*---------------------------------------------------------------------------*/
+/** @} */
+/** @} */

core/net/ipv6/multicast/uip-mcast6-engines.h

@@ -29,6 +29,10 @@
  * This file is part of the Contiki operating system.
  */
 
+/**
+ * \addtogroup uip6-multicast
+ * @{
+ */
 /**
  * \file
  * Header file with definition of multicast engine constants
@@ -43,8 +47,9 @@
 #ifndef UIP_MCAST6_ENGINES_H_
 #define UIP_MCAST6_ENGINES_H_
 
-#define UIP_MCAST6_ENGINE_NONE        0 /* Selecting this disables mcast */
+#define UIP_MCAST6_ENGINE_NONE        0 /**< Selecting this disables mcast */
-#define UIP_MCAST6_ENGINE_SMRF        1
+#define UIP_MCAST6_ENGINE_SMRF        1 /**< The SMRF engine */
-#define UIP_MCAST6_ENGINE_ROLL_TM     2
+#define UIP_MCAST6_ENGINE_ROLL_TM     2 /**< The ROLL TM engine */
 
 #endif /* UIP_MCAST6_ENGINES_H_ */
+/** @} */

core/net/ipv6/multicast/uip-mcast6-route.c

@@ -28,6 +28,10 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \addtogroup uip6-multicast
+ * @{
+ */
 /**
  * \file
  *    Multicast routing table manipulation
@@ -128,3 +132,4 @@ uip_mcast6_route_init()
   list_init(mcast_route_list);
 }
 /*---------------------------------------------------------------------------*/
+/** @} */

core/net/ipv6/multicast/uip-mcast6-route.h

@@ -28,9 +28,13 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \addtogroup uip6-multicast
+ * @{
+ */
 /**
  * \file
- *     Multicast routing table manipulation
+ *    Header file for multicast routing table manipulation
  *
  * \author
  *    George Oikonomou - <oikonomou@users.sourceforge.net>
@@ -45,18 +49,48 @@
 /*---------------------------------------------------------------------------*/
 /** \brief An entry in the multicast routing table */
 typedef struct uip_mcast6_route {
-  struct uip_mcast6_route *next;
+  struct uip_mcast6_route *next; /**< Routes are arranged in a linked list */
-  uip_ipaddr_t group;
+  uip_ipaddr_t group; /**< The multicast group */
-  uint32_t lifetime; /* seconds */
+  uint32_t lifetime; /**< Entry lifetime seconds */
-  void *dag; /* Pointer to an rpl_dag_t struct */
+  void *dag; /**< Pointer to an rpl_dag_t struct */
 } uip_mcast6_route_t;
 /*---------------------------------------------------------------------------*/
 /** \name Multicast Routing Table Manipulation */
 /** @{ */
+
+/**
+ * \brief Lookup a multicast route
+ * \param group A pointer to the multicast group to be searched for
+ * \return A pointer to the new routing entry, or NULL if the route could not
+ *         be found
+ */
 uip_mcast6_route_t *uip_mcast6_route_lookup(uip_ipaddr_t *group);
+
+/**
+ * \brief Add a multicast route
+ * \param group A pointer to the multicast group to be added
+ * \return A pointer to the new route, or NULL if the route could not be added
+ */
 uip_mcast6_route_t *uip_mcast6_route_add(uip_ipaddr_t *group);
-void uip_mcast6_route_rm(uip_mcast6_route_t *defrt);
+
+/**
+ * \brief Remove a multicast route
+ * \param route A pointer to the route to be removed
+ */
+void uip_mcast6_route_rm(uip_mcast6_route_t *route);
+
+/**
+ * \brief Retrieve the count of multicast routes
+ * \return The number of multicast routes
+ */
 int uip_mcast6_route_count(void);
+
+/**
+ * \brief Retrieve a pointer to the start of the multicast routes list
+ * \return A pointer to the start of the multicast routes
+ *
+ * If the multicast routes list is empty, this function will return NULL
+ */
 uip_mcast6_route_t *uip_mcast6_route_list_head(void);
 /*---------------------------------------------------------------------------*/
 /**
@@ -73,3 +107,4 @@ void uip_mcast6_route_init(void);
 /** @} */
 
 #endif /* UIP_MCAST6_ROUTE_H_ */
+/** @} */

core/net/ipv6/multicast/uip-mcast6-stats.c

@@ -27,6 +27,10 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \addtogroup uip6-multicast
+ * @{
+ */
 /**
  * \file
  *    IPv6 multicast forwarding stats maintenance
@@ -47,3 +51,4 @@ uip_mcast6_stats_init(void *stats)
   uip_mcast6_stats.engine_stats = stats;
 }
 /*---------------------------------------------------------------------------*/
+/** @} */

core/net/ipv6/multicast/uip-mcast6-stats.h

@@ -27,6 +27,10 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  * OF THE POSSIBILITY OF SUCH DAMAGE.
  */
+/**
+ * \addtogroup uip6-multicast
+ * @{
+ */
 /**
  * \file
  *     Header file for IPv6 multicast forwarding stats maintenance
@@ -56,15 +60,35 @@
 /*---------------------------------------------------------------------------*/
 /* Stats datatype */
 /*---------------------------------------------------------------------------*/
+/**
+ * \brief A data structure used to maintain multicast stats
+ *
+ * Each engine can extend this structure via the engine_stats field
+ */
 typedef struct uip_mcast6_stats {
+  /** Count of unique datagrams received */
   UIP_MCAST6_STATS_DATATYPE mcast_in_unique;
-  UIP_MCAST6_STATS_DATATYPE mcast_in_all;        /* At layer 3 */
+
-  UIP_MCAST6_STATS_DATATYPE mcast_in_ours;       /* Unique and we are a group member */
+  /** Count of all datagrams received */
-  UIP_MCAST6_STATS_DATATYPE mcast_fwd;           /* Forwarded by us but we are not the seed */
+  UIP_MCAST6_STATS_DATATYPE mcast_in_all;
-  UIP_MCAST6_STATS_DATATYPE mcast_out;           /* We are the seed */
+
+  /** Count of datagrams received for a group that we have joined */
+  UIP_MCAST6_STATS_DATATYPE mcast_in_ours;
+
+  /** Count of datagrams forwarded by us but we are not the seed */
+  UIP_MCAST6_STATS_DATATYPE mcast_fwd;
+
+  /** Count of multicast datagrams originated by us */
+  UIP_MCAST6_STATS_DATATYPE mcast_out;
+
+  /** Count of malformed multicast datagrams seen by us */
   UIP_MCAST6_STATS_DATATYPE mcast_bad;
+
+  /** Count of multicast datagrams correclty formed but dropped by us */
   UIP_MCAST6_STATS_DATATYPE mcast_dropped;
-  void *engine_stats;                            /* Opaque pointer to an engine's additional stats */
+
+  /** Opaque pointer to an engine's additional stats */
+  void *engine_stats;
 } uip_mcast6_stats_t;
 /*---------------------------------------------------------------------------*/
 /* Access macros */
@@ -89,3 +113,5 @@ extern uip_mcast6_stats_t uip_mcast6_stats;
 void uip_mcast6_stats_init(void *stats);
 /*---------------------------------------------------------------------------*/
 #endif /* UIP_MCAST6_STATS_H_ */
+/*---------------------------------------------------------------------------*/
+/** @} */

core/net/ipv6/multicast/uip-mcast6.h

@@ -30,9 +30,11 @@
  */
 
 /**
- * \file
+ * \addtogroup uip6
- *   This header file contains configuration directives for uIPv6
+ * @{
- *   multicast support.
+ */
+/**
+ * \defgroup uip6-multicast IPv6 Multicast Forwarding
  *
  *   We currently support 2 engines:
  *   - 'Stateless Multicast RPL Forwarding' (SMRF)
@@ -42,6 +44,14 @@
  *     in the internet draft:
  *     http://tools.ietf.org/html/draft-ietf-roll-trickle-mcast
  *
+ * @{
+ */
+
+/**
+ * \file
+ *   This header file contains configuration directives for uIPv6
+ *   multicast support.
+ *
  * \author
  *   George Oikonomou - <oikonomou@users.sourceforge.net>
  */
@@ -83,7 +93,11 @@
  * Multicast API. Similar to NETSTACK, each engine must define a driver and
  * populate the fields with suitable function pointers
  */
+/**
+ * \brief The data structure used to represent a multicast engine
+ */
 struct uip_mcast6_driver {
+  /** The driver's name */
   char *name;
 
   /** Initialize the multicast engine */
@@ -110,6 +124,7 @@ struct uip_mcast6_driver {
    *
    * \return 0: Drop, 1: Deliver
    *
+   *
    *        When a datagram with a multicast destination address is received,
    *        the forwarding logic in core is bypassed. Instead, we let the
    *        multicast engine handle forwarding internally if and as necessary.
@@ -158,5 +173,7 @@ extern const struct uip_mcast6_driver UIP_MCAST6;
 #error "Check the value of UIP_CONF_IPV6_RPL in conf files."
 #endif
 /*---------------------------------------------------------------------------*/
-
 #endif /* UIP_MCAST6_H_ */
+/*---------------------------------------------------------------------------*/
+/** @} */
+/** @} */