doc: kconfig: Explain the 'menuconfig' keyword and good uses for it

Takes a while to figure out what it's there for, so explain what it does
and give an example of a good use for it.

Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>

doc/guides/kconfig/index.rst

@@ -351,6 +351,83 @@ the symbols harder to understand, even if code never looks at
 ``FOO_DEVICE_FREQUENCY`` when ``FOO_DEVICE`` is disabled.
 
 
+``menuconfig`` symbols
+**********************
+
+If the definition of a symbol ``FOO`` is immediately followed by other symbols
+that depend on ``FOO``, then those symbols become children of ``FOO``. If
+``FOO`` is defined with ``config FOO``, then the children are shown indented
+relative to ``FOO``. Defining ``FOO`` with ``menuconfig FOO`` instead puts the
+children in a separate menu rooted at ``FOO``.
+
+``menuconfig`` has no effect on evaluation. It's just a display option.
+
+``menuconfig`` can cut down on the number of menus and make the menu structure
+easier to navigate. For example, say you have the following definitions:
+
+.. code-block:: none
+
+   menu "Foo subsystem"
+
+   config FOO_SUBSYSTEM
+   	bool "Foo subsystem"
+
+   if FOO_SUBSYSTEM
+
+   config FOO_FEATURE_1
+   	bool "Foo feature 1"
+
+   config FOO_FEATURE_2
+   	bool "Foo feature 2"
+
+   config FOO_FREQUENCY
+   	int "Foo frequency"
+
+   ... lots of other FOO-related symbols
+
+   endif # FOO_SUBSYSTEM
+
+   endmenu
+
+In this case, it's probably better to get rid of the ``menu`` and turn
+``FOO_SUBSYSTEM`` into a ``menuconfig`` symbol:
+
+.. code-block:: none
+
+   menuconfig FOO_SUBSYSTEM
+   	bool "Foo subsystem"
+
+   if FOO_SUBSYSTEM
+
+   config FOO_FEATURE_1
+   	bool "Foo feature 1"
+
+   config FOO_FEATURE_2
+   	bool "Foo feature 2"
+
+   config FOO_FREQUENCY
+   	int "Foo frequency"
+
+   ... lots of other FOO-related symbols
+
+   endif # FOO_SUBSYSTEM
+
+In the ``menuconfig`` interface, this will be displayed as follows:
+
+.. code-block:: none
+
+   [*] Foo subsystem  --->
+
+Note that making a symbol without children a ``menuconfig`` is meaningless. It
+should be avoided, because it looks identical to a symbol with all children
+invisible:
+
+.. code-block:: none
+
+   [*] I have no children  ----
+   [*] All my children are invisible  ----
+
+
 Checking changes in ``menuconfig``
 **********************************