Documentation fixes

core/net/rime/abc.c

@@ -30,11 +30,11 @@
  *
  * Author: Adam Dunkels <adam@sics.se>
  *
- * $Id: abc.c,v 1.8 2007/03/23 10:46:35 adamdunkels Exp $
+ * $Id: abc.c,v 1.9 2007/03/25 12:05:51 adamdunkels Exp $
  */
 
 /**
- * \addtogroup rime
+ * \addtogroup rime_abc
  * @{
  */
 

core/net/rime/abc.h

@@ -1,3 +1,16 @@
+/**
+ * \addtogroup rime
+ * @{
+ */
+
+/**
+ * \defgroup rime_abc Anonymous best-effort local area broadcast (abc)
+ * @{
+ *
+ * The abc module sends packets to all local area neighbors without
+ * any extra headers that idendtify the sender or receiver.
+ */
+
 /*
  * Copyright (c) 2006, Swedish Institute of Computer Science.
  * All rights reserved.
@@ -28,14 +41,8 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: abc.h,v 1.7 2007/03/19 22:10:16 adamdunkels Exp $
+ * $Id: abc.h,v 1.8 2007/03/25 12:05:51 adamdunkels Exp $
  */
-
-/**
- * \addtogroup rime
- * @{
- */
-
 /**
  * \file
  *         Header file for the Rime module Anonymous BroadCast (abc)
@@ -51,7 +58,12 @@
 
 struct abc_conn;
 
+/**
+ * \brief     Callback structure for abc
+ *
+ */
 struct abc_callbacks {
+  /** Called when a packet has been received by the abc module. */
   void (* recv)(struct abc_conn *ptr);
 };
 
@@ -80,6 +92,16 @@ struct abc_conn {
 void abc_open(struct abc_conn *c, u16_t channel,
 	       const struct abc_callbacks *u);
 
+/**
+ * \brief      Close an abc connection
+ * \param c    A pointer to a struct abc_conn
+ *
+ *             This function closes an abc connection that has
+ *             previously been opened with abc_open().
+ *
+ *             This function typically is called as an exit handler.
+ *
+ */
 void abc_close(struct abc_conn *c);
 
 /**
@@ -98,14 +120,15 @@ void abc_close(struct abc_conn *c);
 int abc_send(struct abc_conn *c);
 
 /**
- * \brief      Pass a packet to the abc layer
+ * \brief      Internal Rime function: Pass a packet to the abc layer
+ *
+ *             This function is used internally by Rime to pass
+ *             packets to the abc layer. Should never be called
+ *             directly.
  *
- *             This function is used by a device driver to pass an
- *             incoming packet to the abc layer. The packet must be
- *             present in the rimebuf buffer when this function is
- *             called.
  */
 void abc_input_packet(void);
 
 #endif /* __BC_H__ */
 /** @} */
+/** @} */

core/net/rime/ctimer.c

@@ -28,12 +28,12 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: ctimer.c,v 1.1 2007/02/28 16:38:51 adamdunkels Exp $
+ * $Id: ctimer.c,v 1.2 2007/03/25 12:05:51 adamdunkels Exp $
  */
 
 /**
  * \file
- *         A brief description of what this file is.
+ *         Callback timer implementation
  * \author
  *         Adam Dunkels <adam@sics.se>
  */

core/net/rime/ctimer.h

@@ -28,12 +28,12 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: ctimer.h,v 1.1 2007/02/28 16:38:51 adamdunkels Exp $
+ * $Id: ctimer.h,v 1.2 2007/03/25 12:05:51 adamdunkels Exp $
  */
 
 /**
  * \file
- *         Module which calls a function after a time
+ *         Header file for the callback timer
  * \author
  *         Adam Dunkels <adam@sics.se>
  */

core/net/rime/ibc.c

@@ -1,3 +1,8 @@
+/**
+ * \addtogroup rime-ibc
+ * @{
+ */
+
 /*
  * Copyright (c) 2006, Swedish Institute of Computer Science.
  * All rights reserved.
@@ -28,12 +33,12 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: ibc.c,v 1.7 2007/03/23 10:46:35 adamdunkels Exp $
+ * $Id: ibc.c,v 1.8 2007/03/25 12:05:51 adamdunkels Exp $
  */
 
 /**
  * \file
- *         A brief description of what this file is.
+ *         Identified best-effort local area broadcast (ibc)
  * \author
  *         Adam Dunkels <adam@sics.se>
  */
@@ -89,3 +94,4 @@ ibc_send(struct ibc_conn *c)
   return 0;
 }
 /*---------------------------------------------------------------------------*/
+/** @} */

core/net/rime/ibc.h

@@ -1,3 +1,16 @@
+/**
+ * \addtogroup rime
+ * @{
+ */
+
+/**
+ * \defgroup rime-ibc Identified best-effort local area broadcast (ibc)
+ * @{
+ *
+ * The ibc module sends packets to all local area neighbors with an a
+ * header that identifies the sender.
+ */
+
 /*
  * Copyright (c) 2006, Swedish Institute of Computer Science.
  * All rights reserved.
@@ -28,12 +41,12 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: ibc.h,v 1.5 2007/03/19 22:10:16 adamdunkels Exp $
+ * $Id: ibc.h,v 1.6 2007/03/25 12:05:51 adamdunkels Exp $
  */
 
 /**
  * \file
- *         A brief description of what this file is.
+ *         Header file for identified best-effort local area broadcast
  * \author
  *         Adam Dunkels <adam@sics.se>
  */
@@ -46,7 +59,12 @@
 
 struct ibc_conn;
 
+/**
+ * \brief     Callback structure for abc
+ *
+ */
 struct ibc_callbacks {
+  /** Called when a packet has been received by the ibc module. */
   void (* recv)(struct ibc_conn *ptr, rimeaddr_t *sender);
 };
 
@@ -55,9 +73,52 @@ struct ibc_conn {
   const struct ibc_callbacks *u;
 };
 
+/**
+ * \brief      Set up an identified best-effort broadcast connection
+ * \param c    A pointer to a struct ibc_conn
+ * \param channel The channel on which the connection will operate
+ * \param u    A struct ibc_callbacks with function pointers to functions that will be called when a packet has been received
+ *
+ *             This function sets up an ibc connection on the
+ *             specified channel. The caller must have allocated the
+ *             memory for the struct ibc_conn, usually by declaring it
+ *             as a static variable.
+ *
+ *             The struct ibc_callbacks pointer must point to a structure
+ *             containing a pointer to a function that will be called
+ *             when a packet arrives on the channel.
+ *
+ */
 void ibc_open(struct ibc_conn *c, u16_t channel,
 	       const struct ibc_callbacks *u);
+
+/**
+ * \brief      Close an ibc connection
+ * \param c    A pointer to a struct ibc_conn
+ *
+ *             This function closes an ibc connection that has
+ *             previously been opened with ibc_open().
+ *
+ *             This function typically is called as an exit handler.
+ *
+ */
 void ibc_close(struct ibc_conn *c);
+
+/**
+ * \brief      Send an anonymous best-effort broadcast packet
+ * \param c    The ibc connection on which the packet should be sent
+ * \retval     Non-zero if the packet could be sent, zero otherwise
+ *
+ *             This function sends an anonymous best-effort broadcast
+ *             packet. The packet must be present in the rimebuf
+ *             before this function is called.
+ *
+ *             The parameter c must point to an abc connection that
+ *             must have previously been set up with ibc_open().
+ *
+ */
 int ibc_send(struct ibc_conn *c);
 
 #endif /* __IBC_H__ */
+/** @} */
+/** @} */

core/net/rime/mesh.h

@@ -1,3 +1,17 @@
+/**
+ * \addtogroup rime
+ * @{
+ */
+
+/**
+ * \defgroup rime-mesh Mesh routing
+ * @{
+ *
+ * The abc module sends packets using multi-hop routing to a specified
+ * receiver somewhere in the network.
+ *
+ */
+
 /*
  * Copyright (c) 2007, Swedish Institute of Computer Science.
  * All rights reserved.
@@ -28,7 +42,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: mesh.h,v 1.5 2007/03/22 17:34:16 adamdunkels Exp $
+ * $Id: mesh.h,v 1.6 2007/03/25 12:05:51 adamdunkels Exp $
  */
 
 /**
@@ -47,9 +61,15 @@
 
 struct mesh_conn;
 
+/**
+ * \brief     Mesh callbacks
+ */
 struct mesh_callbacks {
+  /** Called when a packet is received. */
   void (* recv)(struct mesh_conn *c, rimeaddr_t *from);
+  /** Called when a packet, sent with mesh_send(), is actually transmitted. */
   void (* sent)(struct mesh_conn *c);
+  /** Called when a packet, sent with mesh_send(), times out and is dropped. */
   void (* timedout)(struct mesh_conn *c);
 };
 
@@ -61,11 +81,51 @@ struct mesh_conn {
   const struct mesh_callbacks *cb;
 };
 
+/**
+ * \brief      Open a mesh connection
+ * \param c    A pointer to a struct mesh_conn
+ * \param channels The channels on which the connection will operate; mesh uses 3 channels
+ * \param callbacks Pointer to callback structure
+ *
+ *             This function sets up a mesh connection on the
+ *             specified channel. The caller must have allocated the
+ *             memory for the struct mesh_conn, usually by declaring it
+ *             as a static variable.
+ *
+ *             The struct mesh_callbacks pointer must point to a structure
+ *             containing function pointers to functions that will be called
+ *             when a packet arrives on the channel.
+ *
+ */
 void mesh_open(struct mesh_conn *c, u16_t channels,
 	       const struct mesh_callbacks *callbacks);
 
-int mesh_send(struct mesh_conn *c, rimeaddr_t *dest);
+/**
-
+ * \brief      Close an mesh connection
+ * \param c    A pointer to a struct mesh_conn
+ *
+ *             This function closes an mesh connection that has
+ *             previously been opened with mesh_open().
+ *
+ *             This function typically is called as an exit handler.
+ *
+ */
 void mesh_close(struct mesh_conn *c);
 
+/**
+ * \brief      Send a mesh packet
+ * \param c    The mesh connection on which the packet should be sent
+ * \retval     Non-zero if the packet could be queued for sending, zero otherwise
+ *
+ *             This function sends a mesh packet. The packet must be
+ *             present in the rimebuf before this function is called.
+ *
+ *             The parameter c must point to an abc connection that
+ *             must have previously been set up with mesh_open().
+ *
+ */
+int mesh_send(struct mesh_conn *c, rimeaddr_t *dest);
+
 #endif /* __MESH_H__ */
+/** @} */
+/** @} */

core/net/rime/queuebuf.h

@@ -1,3 +1,16 @@
+/**
+ * \addtogroup rime
+ * @{
+ */
+
+/**
+ * \defgroup rime-queuebuf Rime queue buffer management
+ * @{
+ *
+ * The Rime queue buffer management handles buffers that are queued.
+ *
+ */
+
 /*
  * Copyright (c) 2006, Swedish Institute of Computer Science.
  * All rights reserved.
@@ -28,12 +41,12 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: queuebuf.h,v 1.2 2007/03/20 12:26:23 adamdunkels Exp $
+ * $Id: queuebuf.h,v 1.3 2007/03/25 12:07:10 adamdunkels Exp $
  */
 
 /**
  * \file
- *         A brief description of what this file is.
+ *         Header file for the Rime queue buffer management
  * \author
  *         Adam Dunkels <adam@sics.se>
  */
@@ -49,7 +62,6 @@ void queuebuf_init(void);
 
 struct queuebuf *queuebuf_new_from_rimebuf(void);
 void queuebuf_free(struct queuebuf *b);
-void queuebuf_from_rimebuf(struct queuebuf *b);
 void queuebuf_to_rimebuf(struct queuebuf *b);
 
 void *queuebuf_dataptr(struct queuebuf *b);

core/net/rime/uibc.h

@@ -4,7 +4,7 @@
  */
 
 /**
- * \defgroup uibc Unique Identified best effort local area BroadCast
+ * \defgroup rime_uibc Unique Identified best effort local area Broadcast
  * @{
  *
  * Send one packet that is unique within a time interval.
@@ -41,7 +41,7 @@
  *
  * This file is part of the Contiki operating system.
  *
- * $Id: uibc.h,v 1.1 2007/03/21 23:21:01 adamdunkels Exp $
+ * $Id: uibc.h,v 1.2 2007/03/25 12:07:10 adamdunkels Exp $
  */
 
 /**