apache / nuttx

Apache NuttX is a mature, real-time embedded operating system (RTOS)
https://nuttx.apache.org/
Apache License 2.0
2.81k stars 1.16k forks source link

Suggestion: Add "Description:" header to defconfig file #9598

Open acassis opened 1 year ago

acassis commented 1 year ago

Currently we use the name of the board profile directory to give some clue to users what is the purpose of that defconfig, i.e.: nsh, usbnsh, netnsh, timer, kostest, etc.

But in some case it is not enough, people familiar to NuttX will know what that kostest does, but for a newcomer it doesn't make much sense.

Also now on ESP32S3 we will have two USB Console options: USB Console using USB-JTAG-SERIAL peripheral (that we will call usbconsole) and USB Console using USB OTG Device (that we will call usbnsh).

btashton commented 1 year ago

This information should be in the board documentation (either the docs or the readme for now). This is just delaying that work.

acassis commented 1 year ago

Hi @btashton I totally agree with it, but it is hard to convince people to create a documentation entry for new board profiles. Question: is it possible to create a CI rules to verify if the PR is creating a new defconfig and if so generate an error case the commit is not create an Documentation/ entry?

cederom commented 1 year ago

Just let me know what to put and where and I will help with updating the documentation.. lets keep things coherent and make folks used to the process :-)

Update: On the other hand it would be nice to have "Description" field within the "Defconfig" itself, that would create self-explanatory solution right at the code..I like the idea! :-) Right now some options are obvious only for people who already know them and this is not the way.. for instance some CONFIG options also could be more verbose :-)

Anyways the defconfig name should be self-explanatory: