doc: Added group definitions for most common modules.

git-svn-id: https://src.develer.com/svnoss/bertos/trunk@4548 38d2e660-2303-0410-9eaa-f027e97ec537

diff --git a/Doxyfile-common b/Doxyfile-common
index ca0a9a919ed46a71546cbb316a350b33b3766d90..f15f786066ccdc0d726d9bddaf2b90e84b787361 100644 (file)
--- a/Doxyfile-common
+++ b/Doxyfile-common
@@ -1245,6 +1245,7 @@ PREDEFINED             = __doxygen__ \
                          CONFIG_XMODEM_RECV=1 \
                          CONFIG_XMODEM_SEND=1 \
                          LOG_LEVEL=3 \
+                         CONFIG_HEAP_MALLOC=1 \
                          CONFIG_I2C_DISABLE_OLD_API=0 \
                          COMPILER_VARIADIC_MACROS=1
 

diff --git a/bertos/cfg/log.h b/bertos/cfg/log.h
index cd3e1f3df676a99643f0ab09c20d92a7b243883f..1e4fc150bb2f38621d8deec91a44b90429e4ed75 100644 (file)
--- a/bertos/cfg/log.h
+++ b/bertos/cfg/log.h
@@ -30,7 +30,9 @@
  *
  * -->
  *
- * \addtogroup logging
+ * \defgroup logging Logging facilities
+ * \ingroup core
+ * \{
  * \brief Logging system module.
  *
  * This module implement a simple interface to use the multi level logging system.
@@ -102,11 +104,6 @@
 
 #include <cfg/debug.h>
 
-/**
- * \defgroup logging Logging facilities
- * \{
- */
-
 // Use a default setting if nobody defined a log level
 #ifndef LOG_LEVEL
 #define LOG_LEVEL       LOG_LVL_ERR

diff --git a/bertos/cfg/macros.h b/bertos/cfg/macros.h
index 3ec6b277e51f320f87937098c1a88094ce965a1d..0a721ac5a060f703d00a594ed9ab7cad25ae926e 100644 (file)
--- a/bertos/cfg/macros.h
+++ b/bertos/cfg/macros.h
@@ -30,6 +30,10 @@
  *
  * -->
  *
+ * \defgroup macros General purpose macros
+ * \ingroup core
+ * \{
+ *
  * \brief Common and handy function macros
  *
  * \author Bernie Innocenti <bernie@codewiz.org>
@@ -359,5 +363,7 @@
  */
 typedef uint32_t id_t;
 
+/** \} */ //defgroup macros
+
 #endif /* MACROS_H */
 

diff --git a/bertos/drv/timer.h b/bertos/drv/timer.h
index 50d118a9f8845824f9483ab81ceef7cc0640dd54..83483b9975c4f5a9bc26693a723be828ac2271ae 100644 (file)
--- a/bertos/drv/timer.h
+++ b/bertos/drv/timer.h
@@ -30,6 +30,10 @@
  * Copyright 2000, 2008 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
+ * \defgroup drv_timers Timer module
+ * \ingroup core
+ * \{
+ *
  * \brief Hardware independent timer driver.
  *
  * All timer related functions are implemented in this module. You have several options to use timers:
@@ -313,4 +317,6 @@ INLINE void timer_setSignal(Timer *timer, struct Process *proc, sigmask_t sigs)
 
 #endif /* CONFIG_KERN_SIGNALS */
 
+/** \} */ //defgroup drv_timers
+
 #endif /* DRV_TIMER_H */

diff --git a/bertos/io/kblock.h b/bertos/io/kblock.h
index f2966bafea2fd4def8512452e760a98f6e03e6c1..8bfe384fb3b6cc076e715f217bb99db362f2366a 100644 (file)
--- a/bertos/io/kblock.h
+++ b/bertos/io/kblock.h
@@ -30,10 +30,47 @@
  *
  * -->
  *
- * \author Francesco Sacchi <batt@develer.com>
+ * \defgroup io_kblock KBlock interface
+ * \ingroup core
+ * \{
  *
  * \brief KBlock interface
  *
+ * A block device is a device which can only be read/written
+ * with data blocks of constant size: flash memories,
+ * SD cards, hard disks, etc...
+ * This interface is designed to adapt to most block devices and
+ * use peculiar features in order to save CPU time and memory space.
+ *
+ * There is no init function because you do not have to use this
+ * structure directly, specific implementations will supply their own init
+ * functions.
+ *
+ * Error handling is done in a way similar to standard C library: whenever a
+ * function (eg. kblock_flush()) returns error, you need to check the error
+ * code, which is implementation specific.
+ *
+ * Example of code flow:
+ * \code
+ * // init a KBlock-derived class
+ * Flash fls;
+ * flash_init(&fls.blk, 0);
+ *
+ * // use kblock_* functions to access the derived class
+ * kblock_write(&fls.blk, ...);
+ * if (kblock_flush(&fls.blk) == EOF)
+ * {
+ *     // oops, error occurred!
+ *     int err = kblock_error(&fls.blk);
+ *     // handle Flash specific error conditions
+ *     // ...
+ *     // clear error condition
+ *     kblock_clearerr(&fls.blk);
+ * }
+ * \endcode
+ *
+ * \author Francesco Sacchi <batt@develer.com>
+ *
  * $WIZ$ module_name = "kblock"
  */
 
@@ -116,15 +153,6 @@ typedef struct KBlockPriv
 /**
  * KBlock: interface for a generic block device.
  *
- * A block device is a device which can only be read/written
- * with data blocks of constant size: flash memories,
- * SD cards, hard disks, etc...
- *
- * This interface is designed to adapt to most block devices and
- * use peculiar features in order to save CPU time and memory space.
- *
- * You do not have to use this structure directly, specific implementations
- * will be supplied in the peripheral drivers.
  */
 typedef struct KBlock
 {
@@ -367,4 +395,7 @@ size_t kblock_swReadBuf(struct KBlock *b, void *buf, size_t offset, size_t size)
 size_t kblock_swWriteBuf(struct KBlock *b, const void *buf, size_t offset, size_t size);
 int kblock_swClose(struct KBlock *b);
 
+/** \} */ //defgroup io_kblock
+
+
 #endif /* IO_KBLOCK_H */

diff --git a/bertos/io/kfile.h b/bertos/io/kfile.h
index c7a5bfc924235f6919c96d019fee68405b95f7dd..c5529822ccfa704a5ce89ba8fbd594b8627a04c0 100644 (file)
--- a/bertos/io/kfile.h
+++ b/bertos/io/kfile.h
@@ -31,6 +31,13 @@
  *
  * -->
  *
+ * \defgroup core BeRTOS core functionality
+ * \{
+ *
+ * \defgroup io_kfile KFile interface
+ * \ingroup core
+ * \{
+ *
  * \brief Virtual KFile I/O interface.
  *
  * KFile is a simple, generic interface for file I/O.  It uses an
@@ -325,6 +332,8 @@ void kfile_resync(KFile *fd, mtime_t delay);
 void kfile_init(struct KFile *fd);
 /* @} */
 
+/** \} */ //Defgroup io_kfile
+
 /*
  * Kfile test function.
  */
@@ -332,6 +341,7 @@ int kfile_testSetup(void);
 int kfile_testRun(void);
 int kfile_testRunGeneric(KFile *fd, uint8_t *test_buf, uint8_t *save_buf, size_t size);
 int kfile_testTearDown(void);
+/** \} */ //defgroup core
 
 
 #endif /* KERN_KFILE_H */

diff --git a/bertos/kern/msg.h b/bertos/kern/msg.h
index 2d4672204827495cfef7953960de12067285be06..6cbcc444e371a98bb540a46bbca97af60f157fe8 100644 (file)
--- a/bertos/kern/msg.h
+++ b/bertos/kern/msg.h
@@ -32,15 +32,14 @@
  * -->
  *
  *
- * This module implements a common system for executing
- * a user defined action calling a hook function.
- *
- *
- * \author Bernie Innocenti <bernie@codewiz.org>
+ * \defgroup kern_msg Message box IPC
+ * \ingroup kern
+ * \{
  *
  * \brief Simple inter-process messaging system
  *
- * Handle queues of messages associated an action.
+ * This module implements a common system for executing
+ * a user defined action calling a hook function.
  *
  * A message port is an abstraction used to exchange information
  * asynchronously between processes or other entities such as
@@ -179,6 +178,8 @@
  *     }
  * \endcode
  *
+ * \author Bernie Innocenti <bernie@codewiz.org>
+ *
  * $WIZ$ module_name = "msg"
  * $WIZ$ module_depends = "event", "signal", "kernel"
  */
@@ -290,6 +291,8 @@ INLINE void msg_reply(Msg *msg)
        msg_put(msg->replyPort, msg);
 }
 
+/** \} */ //defgroup kern_msg
+
 int msg_testRun(void);
 int msg_testSetup(void);
 int msg_testTearDown(void);

diff --git a/bertos/kern/proc.h b/bertos/kern/proc.h
index e1181747326224a6d4439cbf7298d5a4656a3601..13bd7bf018f934334e6bd1e8fc01b0a2e098fd84 100644 (file)
--- a/bertos/kern/proc.h
+++ b/bertos/kern/proc.h
@@ -30,6 +30,12 @@
  * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
+ * \defgroup kern Kernel facilities
+ * \{
+ *
+ * \defgroup kern_proc Process (Threads) management
+ * \{
+ *
  * \brief BeRTOS Kernel core (Process scheduler).
  *
  * \author Bernie Innocenti <bernie@codewiz.org>
@@ -396,5 +402,7 @@ INLINE struct Process *proc_current(void)
                #error No cpu_stack_t size supported!
        #endif
 #endif
+/** \} */ //defgroup kern_proc
+/** \} */ //defgroup kern
 
 #endif /* KERN_PROC_H */

diff --git a/bertos/kern/sem.h b/bertos/kern/sem.h
index 1f16acee112f4a71ece2b606ff6ff2a89e1bc6ec..1e59c07fd7a42e2ec16e7e9cf3408d36a95bef11 100644 (file)
--- a/bertos/kern/sem.h
+++ b/bertos/kern/sem.h
@@ -31,6 +31,9 @@
  *
  * -->
  *
+ * \defgroup kern_sem Mutually exclusive semaphores
+ * \ingroup kern
+ * \{
  * \brief Mutually exclusive semaphores.
  *        Shared locking not supported in this implementation.
  *
@@ -69,6 +72,7 @@ bool sem_attempt(struct Semaphore *s);
 void sem_obtain(struct Semaphore *s);
 void sem_release(struct Semaphore *s);
 /* \} */
+/* \} */ //defgroup kern_sem
 
 int sem_testRun(void);
 int sem_testSetup(void);

diff --git a/bertos/kern/signal.h b/bertos/kern/signal.h
index 06c50220334ecc35ca9e57ed214e95d138301a62..408e21e97538f2764b042fd7cb76fbccec8a5dd8 100644 (file)
--- a/bertos/kern/signal.h
+++ b/bertos/kern/signal.h
@@ -31,6 +31,10 @@
  *
  * -->
  *
+ * \defgroup kern_signal Kernel signals
+ * \ingroup kern
+ * \{
+ *
  * \brief Signal module for IPC.
  *
  *
@@ -83,4 +87,6 @@ int signal_testTearDown(void);
 #define SIG_SINGLE   BV(7)  /**< Used to wait for a single event */
 /*\}*/
 
+/* \} */ //defgroup kern_signal
+
 #endif /* KERN_SIGNAL_H */

diff --git a/bertos/mware/event.h b/bertos/mware/event.h
index b797b7eb25a35add0bef5fa02b9509e9149d40e9..e9f9e4a2269d01b36ec665ec85e21cc8589ff99f 100644 (file)
--- a/bertos/mware/event.h
+++ b/bertos/mware/event.h
@@ -30,7 +30,9 @@
  * Copyright 1999, 2001, 2003 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
- * \addtogroup event_handling
+ * \defgroup event_handling Event handling module
+ * \ingroup core
+ * \{
  *
  * \brief Events handling
  *
@@ -107,12 +109,6 @@
        struct Process;
 #endif
 
-/**
- * \defgroup event_handling Events handling module
- * \{
- */
-
-
 /// User defined callback type
 typedef void (*Hook)(void *);
 

diff --git a/bertos/struct/heap.c b/bertos/struct/heap.c
index 4800f1b2048af44c87091ea2afbae58e85f4f812..4c00bd7ca0ed1ebd3b24a6048b6b8f26b8112d24 100644 (file)
--- a/bertos/struct/heap.c
+++ b/bertos/struct/heap.c
@@ -204,6 +204,9 @@ size_t heap_freeSpace(struct Heap *h)
 
 #if CONFIG_HEAP_MALLOC
 
+/**
+ * Standard malloc interface
+ */
 void *heap_malloc(struct Heap* h, size_t size)
 {
        size_t *mem;
@@ -215,6 +218,9 @@ void *heap_malloc(struct Heap* h, size_t size)
        return mem;
 }
 
+/**
+ * Standard calloc interface
+ */
 void *heap_calloc(struct Heap* h, size_t size)
 {
        void *mem;

diff --git a/bertos/struct/heap.h b/bertos/struct/heap.h
index fc36cc7bf910f0fea2b4ebda92b340ad04c730fc..9846079af7a734e73a40752d1353c43ce4779789 100644 (file)
--- a/bertos/struct/heap.h
+++ b/bertos/struct/heap.h
@@ -30,6 +30,10 @@
  * Copyright 1999, 2000, 2001, 2008 Bernie Innocenti <bernie@codewiz.org>
  * -->
  *
+ * \defgroup heap Embedded optimized memory allocator
+ * \ingroup core
+ * \{
+ *
  * \brief Heap subsystem (public interface).
  *
  * \todo Heap memory could be defined as an array of MemChunk, and used
@@ -101,12 +105,19 @@ size_t heap_freeSpace(struct Heap *h);
 
 #if CONFIG_HEAP_MALLOC
 
+/**
+ * \name Compatibility interface with C standard library
+ * \{
+ */
 void *heap_malloc(struct Heap* heap, size_t size);
 void *heap_calloc(struct Heap* heap, size_t size);
 void heap_free(struct Heap* heap, void * mem);
+/** \} */
 
 #endif
 
+/** \} */ //defgroup heap
+
 int heap_testSetup(void);
 int heap_testRun(void);
 int heap_testTearDown(void);