[LinuxBIOS] [RFC] Call for Action: LinuxBIOS foundations

Stefan Reinauer stepan at coresystems.de
Tue Sep 4 11:23:46 CEST 2007


* Corey Osgood <corey.osgood at gmail.com> [070830 02:15]:
> Okay, but how/where should documentation be placed? I can place comments in 
> the code that I write, but there's no guarantee that a new dev will find 
> them. 

Generally, code comments should be doxygen style. This will make them
appear in the code documentation on the web page.

Also, the Wiki is a good place for documentation.

> digging around for them. doxygen is good in some ways, I've found but it 
> only really helps if you can pinpoint a board that uses the function you 
> want, and there's a comment to explain it.

The generated html documentation also has a search function.

What information are you missing from the doxygen docs? Maybe we can add
them?

> Perhaps some pages in the wiki 
> documenting commonly used functions, or perhaps even on a per-file basis? 
> For instance, something like this:

Hm... what about a "LinuxBIOSv2 internals" page with sub categories for
each stage (preram init, linuxbios_ram.rom etc) and have other pages
link to them.

> Title: Commonly used functions in LinuxBIOSv2 pre-ram init (auto.c, 
> raminit.c, *early*.c)
>
> Menu: lists/links function names
>
> Functions: (example)
> pci_write_configX(a, b, c): brief description of what pci_write_configX() 
> does, what parameters need to be passed and what format they're in, perhaps 
> link to another explanation of "device_t dev"
>
> Does this sound like what people want? So far the call for documentation 
> has been clear, just it's unclear what is wanted and where.
>
> -Corey
>

-- 
coresystems GmbH • Brahmsstr. 16 • D-79104 Freiburg i. Br.
      Tel.: +49 761 7668825 • Fax: +49 761 7664613
Email: info at coresystems.dehttp://www.coresystems.de/




More information about the coreboot mailing list