doc: update KConfig style guidelines

Add/update guidelines on how KConfig files should be written and organized
by identifying a common style currenlty used in most areas of the project
and formalizing it.

This should provide an aid for future merge request, code reviews and
refactorings to enable the acting party to better enforce consistency
in KConfig files.

Signed-off-by: Tim Schrader <[email protected]>

Author: ParaZera

doc/contribute/style/kconfig.rst

@@ -3,12 +3,126 @@
 Kconfig Style Guidelines
 ########################
 
-  * Line length of 100 columns or fewer.
-  * Indent with tabs, except for ``help`` entry text which should be placed at
-    one tab plus two extra spaces.
-  * Leave a single empty line between option declarations.
-  * Use Statements like ``select`` carefully, see
-    :ref:`kconfig_tips_and_tricks` for more information.
-  * Format comments as ``# Comment`` rather than ``#Comment``
-  * Insert an empty line before/after each top-level ``if`` and ``endif``
-    statement.
+This document provides style guidelines for writing Kconfig files in the Zephyr
+project. Following these guidelines ensures consistency and readability across
+the codebase, making it easier for developers to understand and maintain
+configuration options.
+
+The following sections provide guidelines with examples to illustrate
+proper Kconfig formatting and naming conventions.
+
+
+Basic Formatting Rules
+**********************
+
+When writing Kconfig files, follow these basic formatting rules:
+
+* **Line length**: Keep lines to 100 columns or fewer.
+* **Indentation**: Use tabs for indentation, except for ``help`` entry text
+  which should be placed at one tab plus two extra spaces.
+* **Spacing**: Leave a single empty line between option declarations.
+* **Comments**: Format comments as ``# Comment`` rather than ``#Comment``.
+* **Conditional blocks**: Insert an empty line before/after each top-level
+  ``if`` and ``endif`` statement.
+
+For guidance on using statements like ``select``, see
+:ref:`kconfig_tips_and_tricks` for more information.
+
+Symbol Naming and Structure
+***************************
+
+The following examples demonstrate proper Kconfig symbol naming and structure:
+
+.. literalinclude:: kconfig_demo_simple.txt
+   :language: kconfig
+   :start-after: start-after-here
+
+.. literalinclude:: kconfig_demo_complex.txt
+   :language: kconfig
+   :start-after: start-after-here
+
+
+Naming Conventions
+******************
+
+* As a general rule, symbols concerning the same component should be distinct
+  from other symbols. This can usually be accomplished by using a common
+  prefix. This prefix can be a simple keyword or, as in the case for drivers,
+  several keywords for more precision.
+
+* A common prefix usually indicates the subsystem or component the symbol
+  belongs to.
+
+* An enabling symbol name should consist of keywords to provide the context
+  of the symbol in a scope from most general to most specific
+  (e.g. *Driver Type* -> *Driver Name*).
+
+* The prompt for an enabling symbol should use the same logic as the symbol
+  name itself but use the keywords in reversed order.
+
+   * Adhering to this style makes searching for symbols easier in the UI
+     because one can filter by a scope keyword.
+
+* When the enabling symbol is dependent on a devicetree node, consider
+  depending on the automatically created ``DT_HAS_<node>_ENABLED`` symbol.
+
+The specific formats by subtree:
+
+* **Drivers (/drivers)**: Use the format ``{Driver Type}_{Driver Name}`` for
+  symbols and ``{Driver Name} {Driver Type} driver`` for prompts.
+
+* **Sensors (/drivers/sensors)**: Use the format ``SENSOR_{Sensor Name}`` for symbols
+  and ``{Sensor Name} {Sensor Type} sensor driver`` for prompts.
+
+* **Architecture (/arch)**: Many symbols are shared across architectures. Before
+  creating new symbols, check if similar ones already exist in other
+  architectures.
+
+Examples
+========
+
+.. note::
+
+   The following examples only show the symbol and prompt lines for brevity.
+
+**Driver Examples:**
+
+.. literalinclude:: kconfig_example_driver.txt
+   :language: kconfig
+   :start-after: start-after-here
+
+**Sensor Examples:**
+
+.. literalinclude:: kconfig_example_sensor.txt
+   :language: kconfig
+   :start-after: start-after-here
+
+Configuration Symbol Organization
+*********************************
+
+When a feature uses config symbols to configure its behavior:
+
+* Use ``menuconfig`` instead of ``config`` to define the enabling feature
+  (even when the config symbol has no prompt).
+
+* Encapsulate the config symbols in an ``if`` statement to declare their
+  dependency on the enabling symbol (this automatically groups these
+  symbols under the enabling symbol in the UI).
+
+* Prefix the config symbol with the enabling symbol's name for scope and
+  context.
+
+* In the prompt of the config symbol, describe what the symbol configures
+  without repeating the scope keywords, because the grouping in the UI
+  provides this context.
+
+File Organization
+*****************
+
+When organizing Kconfig files:
+
+* Keep the Kconfig file close to the source files it configures.
+
+* When dealing with large Kconfig files (e.g. with many config symbols),
+  consider grouping (some of) them into a separate file and import it using the
+  ``source`` directive to improve readability.

doc/contribute/style/kconfig_demo_complex.txt

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Example of a components Kconfig file with one enabling symbol and two config symbols
+
+# start-after-here
+
+# Symbol to enable/disable the feature ("enabling symbol")
+menuconfig ADC_AD4114
+	bool "AD4114 ADC driver"
+	depends on DT_HAS_ADI_AD4114_ADC_ENABLED
+	select SPI
+	default y
+	help
+	  Enable the AD4114 ADC driver.
+
+if ADC_AD4114
+
+# Symbol to configure the behavior of the feature ("config symbol")
+config ADC_AD4114_ACQUISITION_THREAD_STACK_SIZE
+	int "Stack size for the data acquisition thread"
+	default 512
+	help
+	  Size of the stack used for the internal data acquisition
+	  thread.
+
+# Symbol to configure the behavior of the feature ("config symbol")
+config ADC_AD4114_ACQUISITION_THREAD_PRIO
+	int "Priority for the data acquisition thread"
+	default 0
+	help
+	  Priority level for the internal ADC data acquisition thread.
+
+endif # ADC_AD4114

doc/contribute/style/kconfig_demo_simple.txt

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Example of a components Kconfig file with one enabling symbol
+
+# start-after-here
+
+# Symbol to enable/disable the feature ("enabling symbol")
+config ADC_AD405X
+	bool "AD405X ADC driver"
+	depends on DT_HAS_ADI_AD4052_ADC_ENABLED || DT_HAS_ADI_AD4050_ADC_ENABLED
+	select SPI
+	default y
+	help
+	  Enable ADC driver for AD405X.

doc/contribute/style/kconfig_example_driver.txt

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Examples of Kconfig symbols with prompt to enable drivers
+
+# start-after-here
+
+config ADC_AD405X
+	bool "AD405X ADC driver"
+
+config CAN_MAX32
+	bool "MAX32 CAN driver"
+
+config I2C_EMUL
+	bool "I2C emulator driver"

doc/contribute/style/kconfig_example_sensor.txt

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Examples of Kconfig symbols with prompt to enable sensor drivers
+
+# start-after-here
+
+config SENSOR_BMP581
+	bool "BMP581 barometric pressure sensor driver"
+
+config SENSOR_TMP007
+	bool "TMP007 infrared thermopile sensor driver"
+
+config SENSOR_LM75
+	bool "LM75 temperature sensor driver"