Stefan Reinauer wrote:
- Corey Osgood corey.osgood@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