Documentation-related fixes.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@11988 110e8d01-0319-4d1e-a829-52ad28d1bb01

25 files changed, 158 insertions, 107 deletions

diff --git a/doc/rt/Doxyfile_chm b/doc/rt/Doxyfile_chm
index 9ed9c100e..24d899e11 100644
--- a/doc/rt/Doxyfile_chm
+++ b/doc/rt/Doxyfile_chm
@@ -791,8 +791,9 @@ INPUT                  = ./src \
                          ../../os/rt/src \

                          ../../os/rt/include \

                          ../../os/rt/templates \

-                         ../../os/common/oslib/src \

-                         ../../os/common/oslib/include

+                         ../../os/lib/dox \

+                         ../../os/lib/src \

+                         ../../os/lib/include

 

 # This tag can be used to specify the character encoding of the source files

 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

diff --git a/doc/rt/Doxyfile_html b/doc/rt/Doxyfile_html
index 475d3e6b5..fd5608212 100644
--- a/doc/rt/Doxyfile_html
+++ b/doc/rt/Doxyfile_html
@@ -791,8 +791,9 @@ INPUT                  = ./src \
                          ../../os/rt/src \

                          ../../os/rt/include \

                          ../../os/rt/templates \

-                         ../../os/common/oslib/src \

-                         ../../os/common/oslib/include

+                         ../../os/lib/dox \

+                         ../../os/lib/src \

+                         ../../os/lib/include

 

 # This tag can be used to specify the character encoding of the source files

 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

diff --git a/os/lib/dox/lib.dox b/os/lib/dox/lib.dox
new file mode 100644
index 000000000..4dfcdce58
--- /dev/null
+++ b/os/lib/dox/lib.dox
@@ -0,0 +1,85 @@
+/*

+    ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.

+

+    This file is part of ChibiOS.

+

+    ChibiOS is free software; you can redistribute it and/or modify

+    it under the terms of the GNU General Public License as published by

+    the Free Software Foundation; either version 3 of the License, or

+    (at your option) any later version.

+

+    ChibiOS is distributed in the hope that it will be useful,

+    but WITHOUT ANY WARRANTY; without even the implied warranty of

+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

+    GNU General Public License for more details.

+

+    You should have received a copy of the GNU General Public License

+    along with this program.  If not, see <http://www.gnu.org/licenses/>.

+*/

+/**

+ * @defgroup oslib OS Library

+ * @details The OS Library is a set of RTOS extensions compatible with both

+ *          the RT and NIL RTOSes.

+ */

+

+/**

+ * @defgroup oslib_info Version Numbers and Identification

+ * @ingroup oslib

+ */

+

+/**

+ * @defgroup oslib_synchronization Synchronization

+ * @details Synchronization services.

+ * @ingroup oslib

+ */

+

+/**

+ * @defgroup oslib_binary_semaphores Binary Semaphores

+ * @ingroup oslib_synchronization

+ */

+

+/**

+ * @defgroup oslib_mailboxes Mailboxes

+ * @ingroup oslib_synchronization

+ */

+

+/**

+ * @defgroup oslib_pipes Pipes

+ * @ingroup oslib_synchronization

+ */

+

+/**

+ * @defgroup oslib_memory Memory Management

+ * @details Memory Management services.

+ * @ingroup oslib

+ */

+

+/**

+ * @defgroup oslib_memcore Core Memory Manager

+ * @ingroup oslib_memory

+ */

+

+/**

+ * @defgroup oslib_memheaps Memory Heaps

+ * @ingroup oslib_memory

+ */

+

+/**

+ * @defgroup oslib_mempools Memory Pools

+ * @ingroup oslib_memory

+ */

+

+/**

+ * @defgroup oslib_complex Complex Services

+ * @ingroup oslib

+ */

+

+/**

+ * @defgroup oslib_objects_fifos Objects FIFOs

+ * @ingroup oslib_complex

+ */

+

+/**

+ * @defgroup oslib_objects_factory Dynamic Objects Factory

+ * @ingroup oslib_complex

+ */

diff --git a/os/lib/include/chbsem.h b/os/lib/include/chbsem.h
index 77ca30c25..192aec86a 100644
--- a/os/lib/include/chbsem.h
+++ b/os/lib/include/chbsem.h
@@ -20,8 +20,6 @@
 /**

  * @file    chbsem.h

  * @brief   Binary semaphores structures and macros.

- *

- * @addtogroup binary_semaphores

  * @details Binary semaphores related APIs and services.

  *          <h2>Operation mode</h2>

  *          Binary semaphores are implemented as a set of inline functions

@@ -43,6 +41,8 @@
  *          implement the priority inheritance protocol.<br>

  *          In order to use the binary semaphores APIs the

  *          @p CH_CFG_USE_SEMAPHORES option must be enabled in @p chconf.h.

+ *

+ * @addtogroup oslib_binary_semaphores

  * @{

  */

 

diff --git a/os/lib/include/chfactory.h b/os/lib/include/chfactory.h
index 75f52e52f..0f66bf906 100644
--- a/os/lib/include/chfactory.h
+++ b/os/lib/include/chfactory.h
@@ -21,7 +21,7 @@
  * @file    chfactory.h

  * @brief   ChibiOS objects factory structures and macros.

  *

- * @addtogroup objects_factory

+ * @addtogroup oslib_objects_factory

  * @{

  */

 

diff --git a/os/lib/include/chlib.h b/os/lib/include/chlib.h
index 674561cb8..02f50e9c2 100644
--- a/os/lib/include/chlib.h
+++ b/os/lib/include/chlib.h
@@ -23,7 +23,7 @@
  * @details This header includes all the required library headers. This file

  *          is meant do be included by @p ch.h not directly by user.

  *

- * @addtogroup library_info

+ * @addtogroup oslib_info

  * @details OS Library related info.

  * @{

  */

diff --git a/os/lib/include/chmboxes.h b/os/lib/include/chmboxes.h
index 899a8ce1e..fd76b995a 100644
--- a/os/lib/include/chmboxes.h
+++ b/os/lib/include/chmboxes.h
@@ -21,7 +21,7 @@
  * @file    chmboxes.h

  * @brief   Mailboxes macros and structures.

  *

- * @addtogroup mailboxes

+ * @addtogroup oslib_mailboxes

  * @{

  */

 

diff --git a/os/lib/include/chmemcore.h b/os/lib/include/chmemcore.h
index 262796d84..b9b728389 100644
--- a/os/lib/include/chmemcore.h
+++ b/os/lib/include/chmemcore.h
@@ -21,7 +21,7 @@
  * @file    chmemcore.h

  * @brief   Core memory manager macros and structures.

  *

- * @addtogroup memcore

+ * @addtogroup oslib_memcore

  * @{

  */

 

diff --git a/os/lib/include/chmemheaps.h b/os/lib/include/chmemheaps.h
index c0ebcbb99..f20969a32 100644
--- a/os/lib/include/chmemheaps.h
+++ b/os/lib/include/chmemheaps.h
@@ -21,7 +21,7 @@
  * @file    chmemheaps.h

  * @brief   Memory heaps macros and structures.

  *

- * @addtogroup heaps

+ * @addtogroup oslib_memheaps

  * @{

  */

 

diff --git a/os/lib/include/chmempools.h b/os/lib/include/chmempools.h
index f8555c137..60d6a8da9 100644
--- a/os/lib/include/chmempools.h
+++ b/os/lib/include/chmempools.h
@@ -21,7 +21,7 @@
  * @file    chmempools.h

  * @brief   Memory Pools macros and structures.

  *

- * @addtogroup pools

+ * @addtogroup oslib_mempools

  * @{

  */

 

diff --git a/os/lib/include/chobjfifos.h b/os/lib/include/chobjfifos.h
index 51e7bf0a8..dfb0692ef 100644
--- a/os/lib/include/chobjfifos.h
+++ b/os/lib/include/chobjfifos.h
@@ -37,7 +37,7 @@
  *            can be blocking.

  *          .

  *

- * @addtogroup objects_fifo

+ * @addtogroup oslib_objects_fifos

  * @{

  */

 

diff --git a/os/lib/include/chpipes.h b/os/lib/include/chpipes.h
index 9e91614c4..c66c48d68 100644
--- a/os/lib/include/chpipes.h
+++ b/os/lib/include/chpipes.h
@@ -21,7 +21,7 @@
  * @file    chpipes.h
  * @brief   Pipes macros and structures.
  *
- * @addtogroup pipes
+ * @addtogroup oslib_pipes
  * @{
  */
 
diff --git a/os/lib/src/chfactory.c b/os/lib/src/chfactory.c
index dbb13cab8..8384efc2a 100644
--- a/os/lib/src/chfactory.c
+++ b/os/lib/src/chfactory.c
@@ -21,7 +21,7 @@
  * @file    chfactory.c

  * @brief   ChibiOS objects factory and registry code.

  *

- * @addtogroup objects_factory

+ * @addtogroup oslib_objects_factory

  * @details The object factory is a subsystem that allows to:

  *          - Register static objects by name.

  *          - Dynamically create objects and assign them a name.

diff --git a/os/lib/src/chmboxes.c b/os/lib/src/chmboxes.c
index b0ca43877..1b23bf2e0 100644
--- a/os/lib/src/chmboxes.c
+++ b/os/lib/src/chmboxes.c
@@ -21,7 +21,7 @@
  * @file    chmboxes.c

  * @brief   Mailboxes code.

  *

- * @addtogroup mailboxes

+ * @addtogroup oslib_mailboxes

  * @details Asynchronous messages.

  *          <h2>Operation mode</h2>

  *          A mailbox is an asynchronous communication mechanism.<br>

diff --git a/os/lib/src/chmemcore.c b/os/lib/src/chmemcore.c
index bb3832171..5dc3ce446 100644
--- a/os/lib/src/chmemcore.c
+++ b/os/lib/src/chmemcore.c
@@ -21,7 +21,7 @@
  * @file    chmemcore.c

  * @brief   Core memory manager code.

  *

- * @addtogroup memcore

+ * @addtogroup oslib_memcore

  * @details Core Memory Manager related APIs and services.

  *          <h2>Operation mode</h2>

  *          The core memory manager is a simplified allocator that only

@@ -30,8 +30,8 @@
  *          This allocator is meant as a memory blocks provider for the

  *          other allocators such as:

  *          - C-Runtime allocator (through a compiler specific adapter module).

- *          - Heap allocator (see @ref heaps).

- *          - Memory pools allocator (see @ref pools).

+ *          - Heap allocator (see @ref oslib_memheaps).

+ *          - Memory pools allocator (see @ref oslib_mempools).

  *          .

  *          By having a centralized memory provider the various allocators

  *          can coexist and share the main memory.<br>

diff --git a/os/lib/src/chmemheaps.c b/os/lib/src/chmemheaps.c
index fc01b7ccc..2646f2929 100644
--- a/os/lib/src/chmemheaps.c
+++ b/os/lib/src/chmemheaps.c
@@ -21,7 +21,7 @@
  * @file    chmemheaps.c

  * @brief   Memory heaps code.

  *

- * @addtogroup memheaps

+ * @addtogroup oslib_memheaps

  * @details Heap Allocator related APIs.

  *          <h2>Operation mode</h2>

  *          The heap allocator implements a first-fit strategy and its APIs

diff --git a/os/lib/src/chmempools.c b/os/lib/src/chmempools.c
index bd631d5b0..43078c951 100644
--- a/os/lib/src/chmempools.c
+++ b/os/lib/src/chmempools.c
@@ -21,7 +21,7 @@
  * @file    chmempools.c

  * @brief   Memory Pools code.

  *

- * @addtogroup pools

+ * @addtogroup oslib_mempools

  * @details Memory Pools related APIs and services.

  *          <h2>Operation mode</h2>

  *          The Memory Pools APIs allow to allocate/free fixed size objects in

diff --git a/os/lib/src/chpipes.c b/os/lib/src/chpipes.c
index 05b47f369..65df6d530 100644
--- a/os/lib/src/chpipes.c
+++ b/os/lib/src/chpipes.c
@@ -20,8 +20,6 @@
 /**

  * @file    chpipes.c

  * @brief   Pipes code.

- *

- * @addtogroup pipes

  * @details Byte pipes.

  *          <h2>Operation mode</h2>

  *          A pipe is an asynchronous communication mechanism.<br>

@@ -34,6 +32,8 @@
  * @pre     In order to use the pipes APIs the @p CH_CFG_USE_PIPES

  *          option must be enabled in @p chconf.h.

  * @note    Compatible with RT and NIL.

+ *

+ * @addtogroup oslib_pipes

  * @{

  */

 

diff --git a/os/rt/dox/rt.dox b/os/rt/dox/rt.dox
index 76b055761..bd19984ba 100644
--- a/os/rt/dox/rt.dox
+++ b/os/rt/dox/rt.dox
@@ -29,11 +29,21 @@
  */

 

 /**

- * @defgroup config Configuration

+ * @defgroup config_category Configuration

  * @ingroup kernel

  */

 

 /**

+ * @defgroup config Options

+ * @ingroup config_category

+ */

+

+/**

+ * @defgroup conf_checks Checks

+ * @ingroup config_category

+ */

+

+/**

  * @defgroup checks License Checks

  * @ingroup kernel

  */

@@ -46,6 +56,11 @@
  */

 

 /**

+ * @defgroup mem Memory Alignment

+ * @ingroup base

+ */

+

+/**

  * @defgroup system System Management

  * @ingroup base

  */

@@ -56,12 +71,22 @@
  */

 

 /**

+ * @defgroup time_intervals Time and Intervals

+ * @ingroup base

+ */

+

+/**

+ * @defgroup time Virtual Timers

+ * @ingroup base

+ */

+

+/**

  * @defgroup threads Threads

  * @ingroup base

  */

 

 /**

- * @defgroup time Time and Virtual Timers

+ * @defgroup time_measurement Time Measurement

  * @ingroup base

  */

 

@@ -77,11 +102,6 @@
  */

 

 /**

- * @defgroup binary_semaphores Binary Semaphores

- * @ingroup synchronization

- */

-

-/**

  * @defgroup mutexes Mutexes

  * @ingroup synchronization

  */

@@ -102,40 +122,8 @@
  */

 

 /**

- * @defgroup mailboxes Mailboxes

- * @ingroup synchronization

- */

-

-/**

- * @defgroup mem Memory Alignment

- * @details Memory Alignment services.

- * @ingroup kernel

- */

-

-/**

- * @defgroup memory Memory Management

- * @details Memory Management services.

- * @ingroup kernel

- */

-

-/**

- * @defgroup memcore Core Memory Manager

- * @ingroup memory

- */

-

-/**

- * @defgroup heaps Heaps

- * @ingroup memory

- */

-

-/**

- * @defgroup pools Memory Pools

- * @ingroup memory

- */

-

-/**

  * @defgroup dynamic_threads Dynamic Threads

- * @ingroup memory

+ * @ingroup kernel

  */

 

 /**

@@ -149,18 +137,18 @@
  */

 

 /**

- * @defgroup trace Trace

- * @ingroup kernel

+ * @defgroup checks_assertions Checks and Assertions

+ * @ingroup debug

  */

 

 /**

- * @defgroup time_measurement Time Measurement

- * @ingroup kernel

+ * @defgroup trace Tracing

+ * @ingroup debug

  */

 

 /**

  * @defgroup statistics Statistics

- * @ingroup kernel

+ * @ingroup debug

  */

 

 /**

diff --git a/os/rt/include/ch.h b/os/rt/include/ch.h
index a4b6eb257..99eb0d2ab 100644
--- a/os/rt/include/ch.h
+++ b/os/rt/include/ch.h
@@ -20,10 +20,10 @@
 /**

  * @file    ch.h

  * @brief   ChibiOS/RT main include file.

- * @details This header includes all the required kernel headers so it is the

- *          only kernel header you usually want to include in your application.

  *

  * @addtogroup kernel_info

+ * @details This header includes all the required kernel headers so it is the

+ *          only kernel header you usually want to include in your application.

  * @details Kernel related info.

  * @{

  */

diff --git a/os/rt/include/chalign.h b/os/rt/include/chalign.h
index 253b7b315..1d138e895 100644
--- a/os/rt/include/chalign.h
+++ b/os/rt/include/chalign.h
@@ -22,6 +22,7 @@
  * @brief   Memory alignment macros and structures.

  *

  * @addtogroup mem

+ * @details Memory Alignment services.

  * @{

  */

 

diff --git a/os/rt/include/chchecks.h b/os/rt/include/chchecks.h
index 5c38757cd..a1ca063a6 100644
--- a/os/rt/include/chchecks.h
+++ b/os/rt/include/chchecks.h
@@ -20,6 +20,12 @@
 /**

  * @file    chchecks.h

  * @brief   Configuration file checks header.

+ *

+ * @addtogroup conf_checks

+ * @details This module performs a series of checks on configuration data,

+ *          it is able to detect and reject obsolete or incomplete

+ *          @p chconf.h files.

+ * @{

  */

 

 #ifndef CHCHECKS_H

@@ -253,3 +259,5 @@
 /*===========================================================================*/

 

 #endif /* CHCHECKS_H */

+

+/** @} */

diff --git a/os/rt/include/chdebug.h b/os/rt/include/chdebug.h
index 43163bed1..f8a362d5c 100644
--- a/os/rt/include/chdebug.h
+++ b/os/rt/include/chdebug.h
@@ -21,7 +21,7 @@
  * @file    chdebug.h

  * @brief   Debug support macros and structures.

  *

- * @addtogroup debug

+ * @addtogroup checks_assertions

  * @{

  */

 

diff --git a/os/rt/include/chtime.h b/os/rt/include/chtime.h
index c975d104b..264ebcde3 100644
--- a/os/rt/include/chtime.h
+++ b/os/rt/include/chtime.h
@@ -22,6 +22,8 @@
  * @brief   Time and intervals macros and structures.

  *

  * @addtogroup time_intervals

+ * @details This module is responsible for handling of system time and time

+ *          intervals.

  * @{

  */

 

@@ -67,39 +69,6 @@
 /* Module pre-compile time settings.                                         */

 /*===========================================================================*/

 

-/**

- * @brief   System time counter resolution.

- * @note    Allowed values are 16, 32 or 64 bits.

- */

-#if !defined(CH_CFG_ST_RESOLUTION) || defined(__DOXYGEN__)

-#define CH_CFG_ST_RESOLUTION                32

-#endif

-

-/**

- * @brief   System tick frequency.

- * @details Frequency of the system timer that drives the system ticks. This

- *          setting also defines the system tick time unit.

- */

-#if !defined(CH_CFG_ST_FREQUENCY) || defined(__DOXYGEN__)

-#define CH_CFG_ST_FREQUENCY                 1000

-#endif

-

-/**

- * @brief   Time intervals data size.

- * @note    Allowed values are 16, 32 or 64 bits.

- */

-#if !defined(CH_CFG_INTERVALS_SIZE) || defined(__DOXYGEN__)

-#define CH_CFG_INTERVALS_SIZE               32

-#endif

-

-/**

- * @brief   Time types data size.

- * @note    Allowed values are 16 or 32 bits.

- */

-#if !defined(CH_CFG_TIME_TYPES_SIZE) || defined(__DOXYGEN__)

-#define CH_CFG_TIME_TYPES_SIZE              32

-#endif

-

 /*===========================================================================*/

 /* Derived constants and error checks.                                       */

 /*===========================================================================*/

diff --git a/os/rt/src/chdebug.c b/os/rt/src/chdebug.c
index 64e325349..2b4f05452 100644
--- a/os/rt/src/chdebug.c
+++ b/os/rt/src/chdebug.c
@@ -21,7 +21,7 @@
  * @file    chdebug.c

  * @brief   Debug support code.

  *

- * @addtogroup debug

+ * @addtogroup checks_assertions

  * @details Debug APIs and services:

  *          - Runtime system state and call protocol check. The following

  *            panic messages can be generated:

@@ -69,10 +69,8 @@
  *              - S-class function not called from within a critical zone.

  *              - Called from an ISR.

  *            .

- *          - Trace buffer.

  *          - Parameters check.

  *          - Kernel assertions.

- *          - Kernel panics.

  *          .

  * @note    Stack checks are not implemented in this module but in the port

  *          layer in an architecture-dependent way.