doc: minor updates

Restructuring of module section, minor updates.

Signed-off-by: Patrick McHardy <kaber@trash.net>

doc/.gitignore

@@ -1 +1,2 @@
 Doxyfile
+html

doc/Doxyfile.in

@@ -574,7 +574,17 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = src include/dect
+INPUT                  = src/libdect.c \
+			 src/debug.c \
+			 src/timer.c \
+			 src/io.c \
+			 src/identities.c \
+			 src/ie.c \
+			 src/mm.c \
+			 src/cc.c \
+			 src/ss.c \
+			 src \
+			 include/dect
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

include/dect/identities.h

@@ -12,15 +12,12 @@ extern "C" {
 #endif
 
 /**
- * @defgroup identity Identities
- *
- * This module implements the NWK-Layer identities specified in ETSI EN 300 175-6.
- *
+ * @addtogroup identity
  * @{
- */
-
-/**
  * @defgroup identity_ari Access Rights Identity (ARI)
+ *
+ * @sa ETSI EN 300 175-6 (DECT Common Interface - Identities and addressing),
+ *     section 5
  * @{
  */
 
@@ -67,6 +64,10 @@ extern void dect_dump_ari(const struct dect_ari *ari);
 /**
  * @}
  * @defgroup identity_park Portable Access Rights Key (PARK)
+ *
+ * @sa ETSI EN 300 175-6 (DECT Common Interface - Identities and addressing),
+ *     section 6.1
+ *
  * @{
  */
 
@@ -84,6 +85,10 @@ struct dect_park {
 /**
  * @}
  * @defgroup identity_ipui International Portable User ID (IPUI)
+ *
+ * @sa ETSI EN 300 175-6 (DECT Common Interface - Identities and addressing),
+ *     section 6.2
+ *
  * @{
  */
 
@@ -162,6 +167,10 @@ extern bool dect_ipui_cmp(const struct dect_ipui *u1,
 /**
  * @}
  * @defgroup identity_tpui Temporary Portable User ID (TPUI)
+ *
+ * @sa ETSI EN 300 175-6 (DECT Common Interface - Identities and addressing),
+ *     section 6.3
+ *
  * @{
  */
 

include/dect/libdect.h

@@ -74,8 +74,8 @@ static inline void dect_mbuf_reserve(struct dect_msg_buf *mb, unsigned int len)
 /**
  * enum dect_fd_events - file descriptor events
  *
- * @arg DECT_FD_READ:	fd readable
- * @arg DECT_FD_WRITE:	fd writable
+ * @arg DECT_FD_READ:	file descriptor is readable
+ * @arg DECT_FD_WRITE:	file descriptor is writable
  */
 enum dect_fd_events {
 	DECT_FD_READ	= 0x1,

src/identities.c

@@ -8,6 +8,14 @@
  * published by the Free Software Foundation.
  */
 
+/**
+ * @defgroup identity Identities
+ *
+ * This module implements the NWK-Layer identities specified in ETSI EN 300 175-6.
+ *
+ * @{
+ */
+
 #include <stdbool.h>
 #include <stdint.h>
 #include <stdio.h>
@@ -367,3 +375,5 @@ uint32_t dect_build_pmid(const struct dect_pmid *pmid)
 	}
 	return p;
 }
+
+/** @} */

src/io.c

@@ -12,21 +12,24 @@
  * @addtogroup events
  * @{
  *
- * @defgroup io IO
+ * @defgroup io I/O
  *
- * libdect file and socket IO.
+ * libdect file and socket I/O.
  *
- * libdect uses various file descriptors for IO internally. The application
+ * libdect uses various file descriptors for I/O internally. The application
  * using libdect must register the callback functions
  * dect_event_ops::register_fd() and dect_event_ops::unregister_fd() in
  * struct dect_event_ops to allow libdect to register it's file descriptors
- * with the applications' event handler. When an event occurs, the function
+ * with the application's event handler. The function dect_fd_num() can be used
+ * to get the file decriptor number. When an event occurs, the function
  * dect_handle_fd() must be invoked with a bitmask of enum #dect_fd_events
- * specifying the events that occured.
+ * specifying the events that occured. All events except the file descriptor
+ * becoming writable map to #DECT_FD_READ.
  *
  * Each libdect file descriptor contains a storage area of the size specified
  * in dect_event_ops::fd_priv_size, which can be used by the application to
- * associate data with the file descriptor.
+ * associate data with the file descriptor. The function dect_fd_priv() returns
+ * a pointer to this data area.
  *
  * @{
  */

src/lce.c

@@ -8,6 +8,11 @@
  * published by the Free Software Foundation.
  */
 
+/**
+ * @defgroup lce Link Control Entity
+ * @{
+ */
+
 #include <stdio.h>
 #include <stdint.h>
 #include <inttypes.h>
@@ -1092,3 +1097,5 @@ void dect_lce_exit(struct dect_handle *dh)
 	dect_unregister_fd(dh, dh->b_sap);
 	dect_close(dh, dh->b_sap);
 }
+
+/** @} */

src/libdect.c

@@ -8,6 +8,11 @@
  * published by the Free Software Foundation.
  */
 
+/**
+ * @defgroup init Initialization
+ * @{
+ */
+
 #include <stdlib.h>
 #include <unistd.h>
 
@@ -65,3 +70,5 @@ void dect_close_handle(struct dect_handle *dh)
 	dect_free(dh, dh);
 }
 EXPORT_SYMBOL(dect_close_handle);
+
+/** @} */

src/raw.c

@@ -8,6 +8,15 @@
  * published by the Free Software Foundation.
  */
 
+/**
+ * @defgroup raw Raw sockets
+ *
+ * libdect RAW sockets can be used to transmit or receive raw DECT
+ * MAC frames.
+ *
+ * @{
+ */
+
 #include <stdio.h>
 #include <unistd.h>
 #include <string.h>
@@ -20,6 +29,13 @@
 #include <utils.h>
 #include <dect/raw.h>
 
+/**
+ * Transmit a DECT frame on the specified slot
+ *
+ * @param dfd	libdect raw socket file descriptor
+ * @param slot	slot number to transmit on
+ * @param mb	libdect message buffer
+ */
 ssize_t dect_raw_transmit(const struct dect_fd *dfd, uint8_t slot,
 			  const struct dect_msg_buf *mb)
 {
@@ -57,6 +73,11 @@ ssize_t dect_raw_transmit(const struct dect_fd *dfd, uint8_t slot,
 }
 EXPORT_SYMBOL(dect_raw_transmit);
 
+/**
+ * Open a new DECT raw socket
+ *
+ * @param dh	libdect handle
+ */
 struct dect_fd *dect_raw_socket(struct dect_handle *dh)
 {
 	struct sockaddr_dect da;
@@ -81,3 +102,5 @@ err1:
 	return NULL;
 }
 EXPORT_SYMBOL(dect_raw_socket);
+
+/** @} */

src/timer.c

@@ -19,12 +19,13 @@
  * libdect uses various timers internally. The application using libdect must
  * register the callback functions dect_event_ops::start_timer() and
  * dect_event_ops::stop_timer() to allow libdect to register it's timers with
- * the applications' event handler. When a timeout occurs, the function
+ * the application's event handler. When a timeout occurs, the function
  * dect_run_timer() must be invoked.
  *
  * Each libdect timer contains a storage area of the size specified in
  * dect_event_ops::timer_priv_size, which can be used by the application to
- * associate data with the timer.
+ * associate data with the timer. The function dect_timer_priv() returns
+ * a pointer to this data area.
  *
  * @{
  */