From 380a8d3808c38b2e3f2d97a3c2bf5094e0f0386a Mon Sep 17 00:00:00 2001 From: Giovanni Di Sirio Date: Thu, 3 May 2018 11:19:35 +0000 Subject: Documentation-related fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@11988 110e8d01-0319-4d1e-a829-52ad28d1bb01 --- doc/rt/Doxyfile_chm | 5 +-- doc/rt/Doxyfile_html | 5 +-- os/lib/dox/lib.dox | 85 +++++++++++++++++++++++++++++++++++++++++++++ os/lib/include/chbsem.h | 4 +-- os/lib/include/chfactory.h | 2 +- os/lib/include/chlib.h | 2 +- os/lib/include/chmboxes.h | 2 +- os/lib/include/chmemcore.h | 2 +- os/lib/include/chmemheaps.h | 2 +- os/lib/include/chmempools.h | 2 +- os/lib/include/chobjfifos.h | 2 +- os/lib/include/chpipes.h | 2 +- os/lib/src/chfactory.c | 2 +- os/lib/src/chmboxes.c | 2 +- os/lib/src/chmemcore.c | 6 ++-- os/lib/src/chmemheaps.c | 2 +- os/lib/src/chmempools.c | 2 +- os/lib/src/chpipes.c | 4 +-- os/rt/dox/rt.dox | 78 ++++++++++++++++++----------------------- os/rt/include/ch.h | 4 +-- os/rt/include/chalign.h | 1 + os/rt/include/chchecks.h | 8 +++++ os/rt/include/chdebug.h | 2 +- os/rt/include/chtime.h | 35 ++----------------- os/rt/src/chdebug.c | 4 +-- 25 files changed, 158 insertions(+), 107 deletions(-) create mode 100644 os/lib/dox/lib.dox 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 . +*/ +/** + * @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. *

Operation mode

* Binary semaphores are implemented as a set of inline functions @@ -43,6 +41,8 @@ * implement the priority inheritance protocol.
* 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. *

Operation mode

* A mailbox is an asynchronous communication mechanism.
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. *

Operation mode

* 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.
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. *

Operation mode

* 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. *

Operation mode

* 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. *

Operation mode

* A pipe is an asynchronous communication mechanism.
@@ -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,10 +29,20 @@ */ /** - * @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 @@ -45,6 +55,11 @@ * @ingroup kernel */ +/** + * @defgroup mem Memory Alignment + * @ingroup base + */ + /** * @defgroup system System Management * @ingroup base @@ -55,13 +70,23 @@ * @ingroup base */ +/** + * @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 */ @@ -76,11 +101,6 @@ * @ingroup synchronization */ -/** - * @defgroup binary_semaphores Binary Semaphores - * @ingroup synchronization - */ - /** * @defgroup mutexes Mutexes * @ingroup synchronization @@ -101,41 +121,9 @@ * @ingroup synchronization */ -/** - * @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. -- cgit v1.2.3