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

Corey Osgood corey.osgood at gmail.com
Thu Aug 30 02:15:20 CEST 2007


Stefan Reinauer wrote:
> * Corey Osgood <corey.osgood at gmail.com> [070829 20:26]:
>   
>>>> Agreed, I've been frustrated with this as well, even today. v3 should 
>>>> have better documentation, but we still need to bring up to par the 
>>>> documentation on some of the tools.
>>>>     
>>>>         
>>>  Again,... Since you still remember _what_ you have been missing and how
>>> it works now, please try to provide the missing pieces before you get
>>> code blind.
>>>       
>> I'm afraid I'm not quite sure what you mean?
>>     
>
> The documentation. In the last 2 days I read about half a dozen mails
> about how bad the linuxbios documentation is. Looking at the code for
> some years now, many "old" contributors became "code blind", ie. used to
> the weird things. 
>
> For me it's easy to answer to an explicit question, but if you'd ask
> "explain linuxbios" I might just answer questions that you would have
> never asked and the other way around.
>
> So not being "code blind" is very valuable for the project. Still seeing
> the problems that someone coming freshly to the code has is a great
> chance to really improve things for upcoming generations of linuxbios
> hackers.
>
> Stefan

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. I can place comments with the functions, but again it 
requires 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. Perhaps some 
pages in the wiki documenting commonly used functions, or perhaps even 
on a per-file basis? For instance, something like this:

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




More information about the coreboot mailing list