[docs] Fix Doxygen Documentation Generator

This makes the `modm:docs` module generate the doxygen module structure by defining its groups and including the module description in it. This way the module description can be shared between the lbuild discover commands and doxygen. To support this however, all modm modules had to be refactored to name the right `\ingroup modm_module_submodule`. A lot of missing classes were also added to their respective groups. Every lbuild module now also has a description, or at least a description title. You can now do `cd modm/docs; doxygen doxygen.cfg` and the fully featured documentation will appear magically under `modm/docs/html/` for your specific target.
modm-io · Oct 15, 2018 · feb1f3c · feb1f3c
2 parents acad6c1 + 47b4126
commit feb1f3c
Show file tree

Hide file tree

Showing 618 changed files with 2,874 additions and 3,305 deletions.
diff --git a/README.md b/README.md
@@ -15,15 +15,17 @@ process that you can fine-tune to your needs.
 - [This project has a homepage](http://modm.io).<!--/webignore-->
 - Check out our [install instructions][install] and our [getting started guide][guide].
 - Feast your eyes on [lots of working examples][examples].
-<!-- - [API reference is available here][reference]. -->
-<!-- - [Check out our latest quarterly release][releases] with a [beautiful changelog][changelog]. -->
 - Our CI checks every contribution for regressions: <a href="https://circleci.com/gh/modm-io/workflows/modm/tree/develop" style="border-bottom:none">![Build Status](https://circleci.com/gh/modm-io/modm/tree/develop.svg?style=shield)</a>
 - We care [about testing modm][testing].
 
+<!-- - [API reference is available here][reference]. -->
+<!-- - [Check out our latest quarterly release][releases] with a [beautiful changelog][changelog]. -->
+
 This project also has a [technical blog][blog] to document larger design concepts.
 
 - You found a bug? [Open up an issue, we don't bite][issues].
-- You want to contribute? [Read the contribution guidelines][contributing] and [open a pull request][prs].
+- You want to contribute? [Read the contribution guidelines][contrib] and [open a pull request][prs].
+
 <!-- - You want to port modm? [Read our porting guide][porting]. -->
 
 modm is optimized for the harsh requirements of the [Eurobot competition][eurobot],
@@ -66,29 +68,30 @@ git clone --recurse-submodules https://github.com/modm-io/modm.git
 
 ## Targets
 
-modm can generate code for <!--avrcount-->76<!--/avrcount--> AVR and <!--stmcount-->865<!--/stmcount--> STM32 devices, however, there are different levels of support and testing.
+modm can generate code for <!--avrcount-->76<!--/avrcount--> AVR and <!--stmcount-->865<!--/stmcount-->
+STM32 devices, however, there are different levels of support and testing.
 
 <center>
 
-| Device Family | Support                             | Device Family | Support                             |
-|:--------------|:------------------------------------|:--------------|:------------------------------------|
-| AVR           | &#9733;&#9733;&#9733;               | STM32F3       | &#9733;&#9733;&#9733;&#9733;&#9733; |
-| STM32F0       | &#9733;&#9733;&#9733;&#9733;        | STM32F4       | &#9733;&#9733;&#9733;&#9733;&#9733; |
-| STM32F1       | &#9733;&#9733;&#9733;&#9733;        | STM32F7       | &#9733;&#9733;&#9733;&#9733;        |
-| STM32F2       | &#9733;&#9733;&#9733;               | STM32L4       | &#9733;&#9733;&#9733;&#9733;        |
+| Device Family | Support | Device Family | Support |
+|:--------------|:--------|:--------------|:--------|
+| AVR           | ★★★     | STM32F3       | ★★★★★   |
+| STM32F0       | ★★★★    | STM32F4       | ★★★★★   |
+| STM32F1       | ★★★★    | STM32F7       | ★★★★    |
+| STM32F2       | ★★★     | STM32L4       | ★★★★    |
 
 </center>
 
 All of these targets are compiling and booting correctly
-(&#9733;)
+(★)
 and have GPIO and UART working
-(&#9733;&#9733;).
+(★★).
 Most targets have support for basic peripherals, like I2C, SPI and ADC
-(&#9733;&#9733;&#9733;)
+(★★★)
 as well as complicated peripherals, like Timers, CAN and external memory
-(&#9733;&#9733;&#9733;&#9733;).
+(★★★★).
 We also use a few targets in everyday development, which are very well tested
-(&#9733;&#9733;&#9733;&#9733;&#9733;).
+(★★★★★).
 
 We are only a small team of developers and are limited in the amount of targets
 we can support and test in hardware. We have prepared, but currently not finished
@@ -144,9 +147,9 @@ documentation.
 
 ### Drivers
 
-We also have a number of completely target-independent [drivers for external 
+We also have a number of completely target-independent [drivers for external
 devices][drivers] connected via I<sup>2</sup>C, SPI, UART, BitBang, etc.
-Most of these also give you access to the entire device so you 
+Most of these also give you access to the entire device so you
 can easily configure them for you specific needs.
 
 <center>
@@ -218,22 +221,22 @@ Please see [our examples for a complete list][examples] of tested targets and dr
 
 ## How can I contribute?
 
-The easiest way for you and the best way for us to see if something is unclear 
-or missing, is if you use the library and give us some feedback by 
+The easiest way for you and the best way for us to see if something is unclear
+or missing, is if you use the library and give us some feedback by
 [filing a bug report][issues] or if you have a fix already, [opening a pull request][prs].
 
-See [CONTRIBUTING.md][contributing] for our contribution guidelines.
+See [CONTRIBUTING.md][contrib] for our contribution guidelines.
 
 <!--authors-->
 The modm project is maintained by
-Niklas Hauser ([@salkinium](https://github.com/salkinium)) with significant contributions from
-Sascha Schade ([@strongly-typed](https://github.com/strongly-typed)),
-Fabian Greif ([@dergraaf](https://github.com/dergraaf)),
-Kevin Läufer ([@ekiwi](https://github.com/ekiwi)),
-Martin Rosekeit ([@thundernail](https://github.com/thundernail)),
-Daniel Krebs ([@daniel-k](https://github.com/daniel-k)),
-Georgi Grinshpun ([@georgi-g](https://github.com/georgi-g)) and 
-[<!--authorcount-->20<!--/authorcount--> more contributors](https://github.com/modm-io/modm/blob/develop/AUTHORS).
+Niklas Hauser ([\@salkinium](https://github.com/salkinium)) with significant contributions from
+Sascha Schade ([\@strongly-typed](https://github.com/strongly-typed)),
+Fabian Greif ([\@dergraaf](https://github.com/dergraaf)),
+Kevin Läufer ([\@ekiwi](https://github.com/ekiwi)),
+Martin Rosekeit ([\@thundernail](https://github.com/thundernail)),
+Daniel Krebs ([\@daniel-k](https://github.com/daniel-k)),
+Georgi Grinshpun ([\@georgi-g](https://github.com/georgi-g)) and
+[<!--authorcount-->20<!--/authorcount-->  more contributors](https://github.com/modm-io/modm/blob/develop/AUTHORS).
 <!--/authors-->
 
 ## Folder structure
@@ -275,7 +278,7 @@ Georgi Grinshpun ([@georgi-g](https://github.com/georgi-g)) and
 [blog]:            http://blog.salkinium.com
 [changelog]:       https://github.com/modm-io/modm/tree/develop/docs/CHANGELOG.md
 [circle_ci]:       https://circleci.com/gh/modm-io/workflows/modm/tree/develop
-[contributing]:    https://github.com/modm-io/modm/tree/develop/CONTRIBUTING.md
+[contrib]:         https://github.com/modm-io/modm/tree/develop/CONTRIBUTING.md
 [devboards]:       https://github.com/modm-io/modm/tree/develop/src/modm/board
 [drivers]:         https://github.com/modm-io/modm/tree/develop/src/modm/driver
 [eurobot]:         http://www.eurobot.org/

diff --git a/ext/fatfs/module.lb b/ext/fatfs/module.lb
@@ -13,6 +13,15 @@
 
 def init(module):
     module.name = "fatfs"
+    module.description = """\
+# FatFS
+
+Generic FAT Filesystem Module.
+See http://elm-chan.org/fsw/ff/00index_e.html.
+
+!!! warning
+    This version of FatFS is outdated and rarely used in modm.
+"""
 
 def prepare(module, options):
     return True

diff --git a/ext/freertos/module.lb b/ext/freertos/module.lb
@@ -13,6 +13,14 @@
 
 def init(module):
     module.name = "freertos"
+    module.description = """\
+# FreeRTOS
+
+Imported v7.0.1 of FreeRTOS with custom modifications.
+
+!!! warning
+    Please be aware this version is quite outdated and modified for modm.
+"""
 
 def prepare(module, options):
     device = options[":target"]

diff --git a/ext/gcc/module.lb b/ext/gcc/module.lb
@@ -15,6 +15,12 @@
 
 def init(module):
     module.name = "stdc++"
+    module.description = """\
+# C++ Standard Library
+
+A partial port of GCC 8 libstdc++ for AVR.
+See https://github.com/modm-io/avr-libstdcpp.
+"""
 
 
 def prepare(module, options):

diff --git a/ext/ros/module.lb b/ext/ros/module.lb
@@ -12,6 +12,12 @@
 
 def init(module):
     module.name = "ros"
+    module.description = """\
+# ROS Library
+
+Repository of generated messages headers for rosserial.
+See https://github.com/modm-io/ros-lib.
+"""
 
 def prepare(module, options):
     return True

diff --git a/ext/tlsf/README.md b/ext/tlsf/README.md
@@ -1,7 +1,9 @@
-# [tlsf](https://github.com/mattconte/tlsf)
+# TLSF Allocator
+
 Two-Level Segregated Fit memory allocator implementation.
 Written by Matthew Conte ([email protected]).
 Released under the BSD license.
+https://github.com/mattconte/tlsf
 
 Features
 --------

diff --git a/ext/tlsf/module.lb b/ext/tlsf/module.lb
@@ -14,6 +14,7 @@ import math
 
 def init(module):
     module.name = "tlsf"
+    module.description = FileReader("README.md")
 
 def prepare(module, options):
     device = options[":target"]

diff --git a/src/modm/architecture/architecture.hpp b/src/modm/architecture/architecture.hpp
@@ -12,12 +12,6 @@
  */
 // ----------------------------------------------------------------------------
 
-/**
- * \defgroup architecture	Architecture
- *
- * Supported platforms
- */
-
 #ifndef MODM_ARCHITECTURE_HPP
 #define MODM_ARCHITECTURE_HPP
 

diff --git a/src/modm/architecture/detect.hpp b/src/modm/architecture/detect.hpp
@@ -16,50 +16,41 @@
 
 #ifdef __DOXYGEN__
 
-/**
- * \brief	Compiler description
- * \ingroup	platform
- */
+
+/// Compiler description
+/// @ingroup modm_architecture
 #define	MODM_COMPILER_STRING
 
-/**
- * \brief	Possible compilers
- * \ingroup	platform
- */
-//@{
+/// Possible compilers
+/// @ingroup modm_architecture
+/// @{
 #define	MODM_COMPILER_GCC
 #define	MODM_COMPILER_MSVC
-//@}
+/// @}
 
-/**
- * \brief	Operating system description
- * \ingroup	platform
- */
+/// Operating system description
+/// @ingroup modm_architecture
 #define	MODM_OS_STRING
 
-/**
- * \brief	Possible operating systems
- * \ingroup	platform
- */
-//@{
+/// Possible operating systems
+/// @ingroup modm_architecture
+/// @{
 #define	MODM_OS_UNIX
 #define	MODM_OS_LINUX
 #define	MODM_OS_OSX
 #define	MODM_OS_WIN32
 #define	MODM_OS_WIN64
-//@}
+#define	MODM_OS_HOSTED
+#define	MODM_OS_HOSTED_64
+/// @}
 
-/**
- * \brief	CPU description
- * \ingroup	platform
- */
+/// CPU description
+/// @ingroup modm_architecture
 #define	MODM_CPU_STRING
 
-//@{
-/**
- * \brief	Possible CPU definitions
- * \ingroup	platform
- */
+/// Possible CPU definitions
+/// @ingroup modm_architecture
+/// @{
 #define	MODM_CPU_AVR
 #define	MODM_CPU_ATXMEGA
 #define	MODM_CPU_ATMEGA
@@ -68,17 +59,13 @@
 #define	MODM_CPU_ARM
 #define	MODM_CPU_ARM7TDMI
 #define	MODM_CPU_CORTEX_M0
+#define	MODM_CPU_CORTEX_M3
 #define	MODM_CPU_CORTEX_M4
-#define	MODM_CPU_CORTEX_M4
+/// @}
 
-#define	MODM_OS_HOSTED
-#define	MODM_OS_HOSTED_64
-
-//@{
-/**
- * \brief	Memory descriptions
- * \ingroup	platform
- */
+///	Memory descriptions
+/// @ingroup modm_architecture
+/// @{
 #define MODM_ALIGNMENT
 
 #define MODM_ORDER_BIG_ENDIAN
@@ -91,7 +78,7 @@
 #define MODM_IS_LITTLE_ENDIAN
 
 #define	MODM_SIZEOF_POINTER
-//@}
+/// @}
 
 #else //!__DOXYGEN__
 

diff --git a/src/modm/architecture/driver/atomic.hpp b/src/modm/architecture/driver/atomic.hpp
@@ -10,17 +10,6 @@
  */
 // ----------------------------------------------------------------------------
 
-namespace modm
-{
-	/**
-	 * \ingroup	atomic
-	 * \brief	Atomic operations and container
-	 */
-	namespace atomic
-	{
-	}
-}
-
 #include "atomic/flag.hpp"
 #include "atomic/container.hpp"
 #include "atomic/queue.hpp"
diff --git a/src/modm/architecture/driver/atomic/container.hpp b/src/modm/architecture/driver/atomic/container.hpp
@@ -68,7 +68,7 @@ namespace modm
 		 * as it is the case here!
 		 * 
 		 * \author	Fabian Greif
-		 * \ingroup	atomic
+		 * \ingroup	modm_architecture_atomic
 		 */
 		template<typename T>
 		class Container

diff --git a/src/modm/architecture/driver/atomic/flag.hpp b/src/modm/architecture/driver/atomic/flag.hpp
@@ -41,7 +41,7 @@ namespace modm
 		 * }
 		 * \endcode
 		 * 
-		 * \ingroup	atomic
+		 * \ingroup	modm_architecture_atomic
 		 * \author	Fabian Greif
 		 */
 		class Flag

diff --git a/src/modm/architecture/driver/atomic/queue.hpp b/src/modm/architecture/driver/atomic/queue.hpp
@@ -26,7 +26,7 @@ namespace modm
 	namespace atomic
 	{
 		/**
-		 * \ingroup	atomic
+		 * \ingroup	modm_architecture_atomic
 		 * \brief	Interrupt save queue
 		 *
 		 * A maximum size of 254 is allowed for 8-bit mikrocontrollers.

diff --git a/src/modm/architecture/driver/heap/block_allocator.hpp b/src/modm/architecture/driver/heap/block_allocator.hpp
@@ -21,22 +21,22 @@
 #include <modm/architecture/utils.hpp>
 #include <modm/utils/arithmetic_traits.hpp>
 
-/**
- * Memory allocator.
- * 
- * 
- * \tparam	T
- * 		TODO
- * 
- * \tparam	BLOCK_SIZE
- * 		Size of one allocatable block in words (sizeof(T) bytes)
- *		(BLOCKSIZE * sizeof(T) * n) - 4 has to be dividable by 4 for every n
- * 
- * \author	Fabian Greif
- */
-
 namespace modm
 {
+	/**
+	 * Memory allocator.
+	 *
+	 *
+	 * \tparam	T
+	 * 		TODO
+	 *
+	 * \tparam	BLOCK_SIZE
+	 * 		Size of one allocatable block in words (sizeof(T) bytes)
+	 *		(BLOCKSIZE * sizeof(T) * n) - 4 has to be dividable by 4 for every n
+	 *
+	 * \author	Fabian Greif
+	 * \ingroup modm_architecture_heap
+	 */
 	template <typename T, unsigned int BLOCK_SIZE >
 	class BlockAllocator
 	{