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

[Myles Watson]

> Modified:
>    trunk/coreboot-v2/src/Kconfig
> Log:
> Start documenting a few kconfig variables and user-visible options.
>
> Signed-off-by: Uwe Hermann 
> Acked-by: Uwe Hermann

I don't think this is trivial.
> Modified: trunk/coreboot-v2/src/Kconfig
>
> --- trunk/coreboot-v2/src/Kconfig	2009-10-15 14:23:33 UTC (rev 4779)
> +++ trunk/coreboot-v2/src/Kconfig	2009-10-15 17:49:07 UTC (rev 4780)
> @@ -239,12 +243,27 @@
>
> 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.

Maybe some of it should just go into documentation/.

Thanks,
Myles

[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.

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

[Myles Watson]

On Thu, Oct 15, 2009 at 4:33 PM, Uwe Hermann  wrote:
> 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

Yes.  I'd forgotten that.  I do like the fact that you are documenting
things.

Maybe if we started by making the tool that generated the documentation that
would make the decision easier.  My main concern is that we keep it very
clear which options should be set to configure a board vs port Coreboot to a
board.  A good example is GENERATE_ACPI_TABLES vs. HAVE_ACPI_TABLES.
> 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.

I agree.  I just don't like the idea of the help being used for comments.

Does Doxygen handle config options if we format it correctly?
> 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:

Good idea.

Thanks,
Myles

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

[Stefan Reinauer]

On Oct 16, 2009, at 0:33, Uwe Hermann  wrote:
> 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?

I think we already have doxygen to create doxygen like documentation  
so we should be careful to introduce the need for another set of  
tools. But whatever serves the cause best ...
> > 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