[coreboot] [v2] r4780 - trunk/coreboot-v2/src

[Uwe Hermann]

On Thu, Oct 15, 2009 at 12:01:12PM -0600, Myles Watson wrote:
> >  config HAVE_ACPI_TABLES
> >  	bool
> > +	help
> > +	  This variable specifies whether a given board has ACPI table
> > support.
> > +	  It is usually set in mainboard/*/Kconfig.
> > +	  Whether or not the ACPI tables are actually generated by coreboot
> > +	  is configurable by the user via GENERATE_ACPI_TABLES.
> 
> I think comments, not help text is the correct place to put comments about
> CONFIG variables that will never show up in a menu.

I started doing just that recently, but Peter mentioned it may
be a good idea to keep them as "help" texts so we can maybe
auto-generate documentation (for wiki or whatever) out of them easily
(Doxygen-like). Post is at:
http://www.coreboot.org/pipermail/coreboot/2009-October/052966.html

I'm not sure what to do, both methods have their advantages. What do
others think?


> Maybe some of it should just go into documentation/.

Hm, manually maintaining it will very likely fail and we'll have a
bit-rotting document very soon (like most of the other documents we
have right now). Keeping the help text near the variable (just as we
keep Doxygen-style code comments near the function they document) is a
good idea, IHMO. If we want an extra document with all config options
we should write up some scripts to generate that, as is done with
the oldconfig ones, see:

http://www.coreboot.org/Coreboot_Options


Uwe.
-- 
http://www.hermann-uwe.de  | http://www.randomprojects.org
http://www.crazy-hacks.org | http://www.unmaintained-free-software.org