From 67910a121986247af7df567dee97ff6ab42a45d2 Mon Sep 17 00:00:00 2001
From: Francisco Molina <femolina@uc.cl>
Date: Wed, 15 Apr 2020 10:25:31 +0200
Subject: [PATCH] doc/creating-modules.md: correct PSEUDOMODULES documentation

---
 doc/doxygen/src/creating-modules.md | 81 ++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 6 deletions(-)

diff --git a/doc/doxygen/src/creating-modules.md b/doc/doxygen/src/creating-modules.md
index 3a99733872..616e868041 100644
--- a/doc/doxygen/src/creating-modules.md
+++ b/doc/doxygen/src/creating-modules.md
@@ -80,9 +80,78 @@ An example can be found in
 
 Pseudomodules                                                  {#pseudomodules}
 =============
-Pseudomodules are modules that do not have any code. Their main use cases are
-to provide base information for dependencies to other modules or information to
-the code base via the `MODULE_<MODULENAME>` macro. Pseudomodules can provide
-header files too, if need be. To create a pseudomodule just add its name to
-`makefiles/pseudomodules.inc.mk` with `PSEUDOMODULES += <modulename>` in
-alphabetical order.
+Pseudomodules are modules that are not static libraries, i.e. do not generate a
+`<module name>.a` file.
+
+To create a pseudomodule just add its name to `makefiles/pseudomodules.inc.mk`
+with `PSEUDOMODULES += <modulename>` in alphabetical order.
+
+A Pseudomodule may or may not have a source file associated with it. To make the
+distinction between them we will refer to those that don't as true-Pseudomodules.
+
+The main use case for true-Pseudomodules is to provide base information for
+dependencies to other modules or information to the code base via the
+`MODULE_<MODULENAME>` macro.
+
+Pseudomodules with source code exist under a "real" `MODULE` since they will
+generate a `<pseudomodule_name>.o` file grouped under that `MODULE`s
+`<module_name>.a` file.
+
+These modules appear in RIOT under two forms:
+
+1. Conditionally included source files:
+
+  ```
+    foo/
+    |----foo_bar.c
+    |----foo.c
+    |----Makefile
+  ```
+
+In `foo/Makefile` you add the source file to the `SRC` variable, conditioned on
+the Pseudomodule inclusion
+
+  ```mk
+  ifneq (,$(filter foo_bar,$(USEMODULE)))
+    SRC += foo_bar.c
+  endif
+  ```
+
+See `sys/net/ble/skald` for an example in code.
+
+2. Using the `SUBMODULES` mechanism:
+
+  ```
+    foo/
+    |----spam.c
+    |----ham.c
+    |----eggs.c
+    |----Makefile
+  ```
+
+  ```mk
+  # make all code end up in "foo_bar.a", this can be any name
+  MODULE := foo_bar
+
+  # ensure that "foo_ham" or "bar_foo_ham" builds "foo_ham.c".
+  BASE_MODULE := foo
+
+  # list of source files that are not SUBMODULES
+  SRC := spam.c
+
+  # enable submodules by setting SUBMODULES = 1
+  SUBMODULES = 1
+  ```
+
+When using `SUBMODULES` in a `MODULE` all `SRC` file excluded from `foo/Makefile`
+will be considered `SUBMODULES`. In the example above `ham.c` and `eggs.c`.
+These source files will be conditionally included depending if the modules have
+been added, i.e. `USEMODULE += foo_ham foo_eggs` (it's the same as case 1 but
+handled automatically in `Makefile.base`).
+
+The `SUBMODULES` mechanism is more flexible since `BASE_MODULE` allows matching
+the only parts of compounded module names and only match against part of that name.
+
+See `sys/ztimer/Makefile` for an example in code.
+
+`SUBMODULES` can also be true-pseudomodules.
\ No newline at end of file