doc/kconfig: update to current behaviour and used files

doc/doxygen/src/kconfig/kconfig.md

@@ -92,12 +92,6 @@ will not longer be overridable by means of CFLAGS (e.g. set on the
 compilation command or on a Makefile). Consider this if you are getting a
 'redefined warning'.
 
-## A note on the usage of the 'clean' command
-When using Kconfig as the configurator for RIOT, configuration symbols may be
-used in Makefiles through the build system. For this to work properly make
-sure that when cleaning an application you call `make clean && make all`,
-instead of `make clean all`.
-
 ---
 # Integration into the build system    {#kconfig-integration-into-build-system}
 
@@ -134,27 +128,32 @@ Kconfig symbol as documented in [Appendix A](#kconfig-appendix-a).
 
 ### 2. Merging all configuration sources         {#kconfig-steps-merge-configs}
 In this step configuration values are taken from multiple sources and merged
-into a single `merged.config` configuration file. This file is temporary and is
+into a single `out.config` configuration file. This file is temporary and is
 removed on clean. If the user needs to save a particular configuration
 set, a backup has to be saved (this can be done using the menuconfig interface)
 so it can be loaded later in this step.
 
-To accomplish merging of multiple input files, the `mergeconfig` script is
+To accomplish merging of multiple input files, the `genconfig` script is
 used.  Note that **the order matters**: existing configuration values are
 merged in the order expressed in the input section, where the last value
 assigned to a parameter has the highest priority. If no configuration files are
 available all default values will be applied.
 
-`merged.config` is the only configuration input for the `autoconf.h` in the
+`out.config` is the only configuration input for the `autoconf.h` in the
 [generation step](#kconfig-steps-header-gen).
 
+Additionally this step generates a file `out.config.d` which holds the
+information of all the used Kconfig files in Makefile format. This file is
+included by the build system and allows to re-trigger the generation of
+`out.conf` whenever a Kconfig file is modified.
+
 #### Input
 - Optional:
     - `$ (APPDIR)/app.config`: Application specific default configurations.
     - `$ (APPDIR)/user.config`: Configurations saved by user.
 
 #### Output
-- `$ (GENERATED_DIR)/merged.config` file.
+- `$ (GENERATED_DIR)/out.config` file.
 
 ### 3. Menuconfig execution (optional)
 Menuconfig is a graphical interface for software configuration. It is used for
@@ -162,7 +161,7 @@ the configuration of the Linux kernel. This section explains the process
 that occurs when RIOT is being configured using the menuconfig interface.
 
 The main `Kconfig` file is used in this step to show the configurable
-parameters of the system. Kconfig will filter innaplicable parameters (i.e.
+parameters of the system. Kconfig will filter inapplicable parameters (i.e.
 parameters exposed by modules that are not being used) based on the file
 `$ (GENERATED_DIR)/Kconfig.dep` generated in step 1.
 
@@ -176,26 +175,29 @@ information see
 Note that if Kconfig is not used to configure a module, the corresponding
 header files default values will be used.
 
-`merged.config` is one of the inputs for menuconfig. This means that any
+`out.config` is one of the inputs for menuconfig. This means that any
 configuration that the application defines in the `app.config` or a backup
 configuration from the user in `user.config` are taken into account on the
 first run (see [Appendix C](#kconfig-appendix-c)).
 
 In this step the user chooses configuration values (or selects the minimal
-configuration) and saves it to the `merged.config` file. Here the user can
+configuration) and saves it to the `out.config` file. Here the user can
 choose to save a backup configuration file for later at a different location
 (e.g. a `user.config` file in the application folder).
 
+If any changes occur to `out.config`, the
+[generation of autoconf.h](#kconfig-steps-header-gen) is executed automatically.
+
 #### Input
 - `/Kconfig` file.
 - Optional:
     - `$ (APPDIR)/app.config`
     - `$ (APPDIR)/user.config`
-    - `$ (GENERATED_DIR)/merged.config`
+    - `$ (GENERATED_DIR)/out.config`
 
 #### Output
-- Updated `$ (GENERATED_DIR)/merged.config` file.
+- Updated `$ (GENERATED_DIR)/out.config` file.
-- `$ (GENERATED_DIR)/merged.config.old` backup file.
+- `$ (GENERATED_DIR)/out.config.old` backup file.
 
 ### 4. Generation of the autoconf.h header          {#kconfig-steps-header-gen}
 With the addition of Kconfig a dependency has been added to the build
@@ -205,30 +207,31 @@ that should be used to configure modules in RIOT:
 `CONFIG_<module>_<parameter>`.
 
 In order to generate the `autoconf.h` file the `genconfig` script is used.
-Inputs for this script are the main `Kconfig` file and `merged.config`
+Inputs for this script are the main `Kconfig` file and `out.config`
 configuration file, which holds the selected values for the exposed parameters.
 
 #### Input:
-- `$ (GENERATED_DIR)/merged.config` file.
+- `$ (GENERATED_DIR)/out.config` file.
 - Main `Kconfig` file exposing configuration of modules.
 
 #### Output:
 - `$ (GENERATED_DIR)/autoconf.h` configuration header file.
-- `$ (GENERATED_DIR)/out.config` file.
+- Optional:
+    - `$ (GENERATED_DIR)/deps/*/*.h` header files that allow incremental builds
 
 
 ### Summary of files
 These files are defined in `kconfig.mk`.
 
-| File              | Description |
+| File           | Description |
-| ----------------- | ----------- |
+| ---------------| ----------- |
-| `Kconfig`           | Defines configuration options of modules. |
+| `Kconfig`      | Defines configuration options of modules. |
-| `Kconfig.dep`       | Holds a list of the modules that are being compiled. |
+| `Kconfig.dep`  | Holds a list of the modules that are being compiled. |
-| `app.config`        | Holds default application configuration values. |
+| `app.config`   | Holds default application configuration values. |
-| `user.config`       | Holds configuration values applied by the user. |
+| `user.config`  | Holds configuration values applied by the user. |
-| `merged.config`     | Holds configuration from multiple sources. Used to generate header. |
+| `out.config`   | Configuration file containing all the symbols defined in `autoconf.h`. |
-| `autoconf.h`        | Header file containing the macros that applied the selected configuration. |
+| `out.config.d` | Dependency file of `out.config` containing the list of Kconfig files used to generate it. |
-| `out.config`        | Configuration file containing all the symbols defined in `autoconf.h`. |
+| `autoconf.h`   | Header file containing the macros that applied the selected configuration. |
 
 ## Kconfig symbols in Makefiles
 As '.config' files have Makefile syntax they can be included when building,
@@ -254,10 +257,10 @@ application's Makefile. The symbols will not be defined until after including
 ---
 # Transition phase                                  {#kconfig-transition-phase}
 ## Making configuration via Kconfig optional  {#kconfig-configuration-optional}
-During transition to the usage of Kconfig as the main configurator for RIOT,
+During transition to the usage of Kconfig as the main configuration tool for
-the default behavior will be the traditional one: expose configuration options
+RIOT, the default behavior will be the traditional one: expose configuration
-in header files and use CFLAGS as inputs. To allow optional configuration via
+options in header files and use CFLAGS as inputs. To allow optional
-Kconfig, a convention will be used when writing Kconfig files.
+configuration via Kconfig, a convention will be used when writing Kconfig files.
 
 Modules should be contained in their own `menuconfig` entries, this way the user
 can choose to enable the configuration via Kconfig for an specific module.
@@ -548,14 +551,18 @@ the menuconfig graphical interface or writing '.config' files by hand.
 As explained in the
 ['Configuration sources merging step'](#kconfig-steps-merge-configs)
 of the configuration process, configuration from multiple sources are loaded to
-create a single `merged.config` file, and the order of merging matters: last
+create a single `out.config` file, and the order of merging matters: last
 file has priority.
 
-While editing values directly via '.config' files `merged.config` will be
+While editing values directly via '.config' files `out.config` will be
-re-built. Once the user decides to edit `merged.config` directly using
+re-built. The user can also use menuconfig interface to modify the configuration
-menuconfig, the file will not be re-built anymore, and any changes by manually
+file (this is the recommended way, as it gives access to much more information
-editing the source files will have no effect. To go back to manual edition
+regarding dependencies and default values of the symbols). Menuconfig will
-a `make clean` has to be issued in the application directory.
+change `out.config` directly (a backup file `out.config.old` will be kept).
+
+**It is recommended to save backups of the configurations, as any change on the
+configuration sources would re-trigger the merging process and overwrite
+`out.config`.**
 
 ## Appendix D: A few key aspects while exposing a macro to Kconfig {#kconfig-appendix-d}
 A macro that holds a 0 or 1 is modelled in Kconfig as a `bool` symbol. References to this macro