[LinuxBIOS] [RFC] Call for Action: LinuxBIOS foundations
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
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,
Menu: lists/links function names
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.
More information about the coreboot