doc: update KConfig style guidelines #95132

ParaZera · 2025-08-28T22:20:57Z

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.

Part of #7272

github-actions · 2025-08-28T22:21:45Z

Hello @ParaZera, and thank you very much for your first pull request to the Zephyr project!
Our Continuous Integration pipeline will execute a series of checks on your Pull Request commit messages and code, and you are expected to address any failures by updating the PR. Please take a look at our commit message guidelines to find out how to format your commit messages, and at our contribution workflow to understand how to update your Pull Request. If you haven't already, please make sure to review the project's Contributor Expectations and update (by amending and force-pushing the commits) your pull request if necessary.
If you are stuck or need help please join us on Discord and ask your question there. Additionally, you can escalate the review when applicable. 😊

doc/contribute/style/kconfig.rst

kartben · 2025-08-29T07:18:14Z

doc/contribute/style/kconfig.rst

+
+.. code-block:: kconfig
+
+   # symbol to enable/disable the feature = "enabling symbol"


Suggested change

# symbol to enable/disable the feature = "enabling symbol"

# Symbol to enable/disable the feature ("enabling symbol")

Adjust everywhere

@ParaZera you might have missed this comment

Yeah, I missed it 😅 . Now, every comment should be updated as you requested.

doc/contribute/style/kconfig.rst

doc/contribute/style/kconfig_demo_simple.txt

pdgendt · 2025-09-11T07:00:02Z

doc/contribute/style/kconfig_demo_complex.txt

@@ -0,0 +1,27 @@
+# Symbol to enable/disable the feature ("enabling symbol")
+menuconfig ADC_ADI_AD4114
+	bool "AD4114 (ADI) ADC driver"


Not sure about the abbreviated manufacturer mentioned here. I'd write it in full, or leave it out.

Suggested change

bool "AD4114 (ADI) ADC driver"

bool "AD4114 (Analog Devices, Inc) ADC driver"

My rationale behind using the abbreviated form is that it might be easier to search for the manufacturer in the UI.

I updated the manufacturer names in the examples to match common occurrences in the repository.

nordicjm

this doesn't improve things

nordicjm · 2025-10-02T09:47:13Z

doc/contribute/style/kconfig_demo_simple.txt

+config ADC_ADI_AD405X
+	bool "AD405X (Analog Devices, Inc) ADC driver"


this isn't even right drivers/adc/Kconfig.ad405x has:

Suggested change

config ADC_ADI_AD405X

bool "AD405X (Analog Devices, Inc) ADC driver"

config ADC_AD405X

bool "AD405X ADC driver"

Yes, it different from the real KConfig file right now. But the PR is trying to set up guidelines as requested in issue ##7272 to have a more consistent way of naming Kconfig symbols.

Can you be more specific on what things you feel would not be improved by this guideline so I can better address it?

This is not an improvement, the original is fine

I'd argue against this because:

This circumvents potential naming conflicts as a manufacturer will not release two devices under the same name while different manufacturers might at the cost of minimally longer Kconfig symbols

Especially in the prompt it enables better search capabilities (because more information is available)

This circumvents potential naming conflicts as a manufacturer will not release two devices under the same name while different manufacturers might at the cost of minimally longer Kconfig symbols

this is false though? Let's take the 34063 which is an old DC/DC converter, or even the humble 1n4001 diode, there are many different manufactures for both of these, so to claim that a device will not have another manufacturer is absurd, plus what happens if the company gets bought out or renamed? Not withstanding that no-one really cares who the manufacturer of it is, if you have a board with the part, you are going to be looking up the part number, you're not going to look up "ADI" then go through every single drivers Kconfig to see if you can find one that works

I understand the reasoning behind it and have updated the PR accordingly. 👍

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]>

pdgendt · 2025-10-10T10:22:29Z

doc/contribute/style/kconfig.rst

+.. literalinclude:: kconfig_example_driver.txt
+   :language: kconfig


Instead of copying the file, just include the actual file

Suggested change

.. literalinclude:: kconfig_example_driver.txt

:language: kconfig

.. literalinclude:: ../../../drivers/adc/Kconfig.ad4114

:language: kconfig

Same for the sensor sample.

Currently the examples are not a 1 to 1 copy of the drivers Kconfig (e.g. the AD4114 Kconfig does not use menuconfig)

If we want to use real Kconfig files I would exchange them with the first refactorings in a different PR, as I first want to have an agreed style before changing the code.

Also why we might not want to remove the samples:

I wanted to show a "simple" and a "complex" configuration. When using real drivers config, the simple example might get extended without the documentation getting updated with another simple example

The document looses the code annotations to outline what an "enabling symbol" and "config symbol" is

sonarqubecloud · 2025-10-10T10:22:31Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

nordicjm · 2025-10-13T08:41:56Z

doc/contribute/style/kconfig_example_sensor.txt

@@ -0,0 +1,8 @@
+config SENSOR_BMP581
+	bool "BMP581 barometric pressure sensor driver"
+


shouldn't these (and the drivers) have the depends on and select and default statements?

zephyrbot added the area: Documentation label Aug 28, 2025

zephyrbot requested review from carlescufi, kartben and nashif August 28, 2025 22:21

zephyrbot assigned kartben and carlescufi Aug 28, 2025

ParaZera force-pushed the doc/kconfig-guidelines branch from 8193d69 to d381ed0 Compare August 28, 2025 22:45

pdgendt reviewed Aug 29, 2025

View reviewed changes

doc/contribute/style/kconfig.rst Outdated Show resolved Hide resolved

doc/contribute/style/kconfig.rst Outdated Show resolved Hide resolved

doc/contribute/style/kconfig.rst Outdated Show resolved Hide resolved

carlescufi requested a review from nordicjm August 29, 2025 12:33

ParaZera force-pushed the doc/kconfig-guidelines branch 2 times, most recently from 78ff9dc to f98ad96 Compare August 29, 2025 13:17

ParaZera requested a review from pdgendt August 29, 2025 13:25

kartben reviewed Sep 9, 2025

View reviewed changes

ParaZera force-pushed the doc/kconfig-guidelines branch 5 times, most recently from 381e145 to 7e76895 Compare September 9, 2025 19:16

pdgendt reviewed Sep 10, 2025

View reviewed changes

doc/contribute/style/kconfig_demo_simple.txt Outdated Show resolved Hide resolved

ParaZera force-pushed the doc/kconfig-guidelines branch from 7e76895 to 6a629ae Compare September 10, 2025 18:52

pdgendt reviewed Sep 11, 2025

View reviewed changes

ParaZera force-pushed the doc/kconfig-guidelines branch from 6a629ae to cd4e944 Compare September 11, 2025 14:14

nordicjm requested changes Oct 2, 2025

View reviewed changes

ParaZera force-pushed the doc/kconfig-guidelines branch from cd4e944 to f7bacd2 Compare October 10, 2025 10:18

pdgendt reviewed Oct 10, 2025

View reviewed changes

ParaZera requested a review from nordicjm October 10, 2025 12:01

nordicjm reviewed Oct 13, 2025

View reviewed changes


		.. code-block:: kconfig

		# symbol to enable/disable the feature = "enabling symbol"

	# symbol to enable/disable the feature = "enabling symbol"
	# Symbol to enable/disable the feature ("enabling symbol")

	bool "AD4114 (ADI) ADC driver"
	bool "AD4114 (Analog Devices, Inc) ADC driver"

		config ADC_ADI_AD405X
		bool "AD405X (Analog Devices, Inc) ADC driver"

		.. literalinclude:: kconfig_example_driver.txt
		:language: kconfig

		@@ -0,0 +1,8 @@
		config SENSOR_BMP581
		bool "BMP581 barometric pressure sensor driver"

doc: update KConfig style guidelines #95132

Are you sure you want to change the base?

doc: update KConfig style guidelines #95132

Uh oh!

Conversation

ParaZera commented Aug 28, 2025

Uh oh!

github-actions bot commented Aug 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nordicjm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Oct 10, 2025

Quality Gate passed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants