Is documentation in the kernel code desired?
Hi everybody!
I'm currently going through some code in the kernel to understand how things work. I have to admit that some pieces are poorly documented. Especially for kernel newbies like me, documentation in the code could help a lot. I think that some lines of documentation at the top of important functions would be nice. I'm asking, because I don't know if documentation in the code is really desired as it blows up the code and requires changes in the documentation, too if the code is modified.
Code-documentation could also be a nice project for the kernel-janitors.
Regards,
Andi
_______________________________________________
Kernel-janitors mailing list
[email protected]
https://lists.osdl.org/mailman/listinfo/kernel-janitors
Quoted 9 lines · On Fri, 13 Oct 2006 19:53:05 +0200 Andi Drebes wrote:
Hi everybody!
I'm currently going through some code in the kernel to understand how things work. I have to admit that some pieces are poorly documented. Especially for kernel newbies like me, documentation in the code could help a lot. I think that some lines of documentation at the top of important functions would be nice. I'm asking, because I don't know if documentation in the code is really desired as it blows up the code and requires changes in the documentation, too if the code is modified.
Code-documentation could also be a nice project for the kernel-janitors.
In general, yes, we want/need more documentation.
Caveat: don't document obvious things like:
i++; /* increment the array index */
It's more important to document why something is done and generally how it is done. "What" is important, but could easily be one or two sentences, while the why and how may take much more.
It's not clear to me that this is a good kernel-janitors project, but I don't want to discourage anyone either. However, I've tried documenting some parts of the kernel code and it's fairly difficult to do so in lots of places, unless you are very familiar with the code.
Where to put the documentation:
Unless it's a small book, putting it before the function body in kernel-doc is the best place for it. If it's a small book, most developers (unscientfic :) seem to prefer to put it in the kernel Documentation/ directory. OTOH, some people want to move as much as possible out of that directory and into the source files. I don't agree that that is always the right answer.
Anyway, if any of you can generate and send documentation, please go for it.
---
~Randy
_______________________________________________
Kernel-janitors mailing list
[email protected]
https://lists.osdl.org/mailman/listinfo/kernel-janitors
Quoted 3 lines
Caveat: don't document obvious things like:
i++; /* increment the array index */
That's quite clear ;)
i++; /* increment the array index */
/* The line above is a comment :D */
/* ... */Quoted 4 lines
It's not clear to me that this is a good kernel-janitors project, but I don't want to discourage anyone either. However, I've tried documenting some parts of the kernel code and it's fairly difficult to do so in lots of places, unless you are very familiar with the code.
Well, in fact I didn't mean "project". I don't want to start a big document-every-line-in-the-kernel-project. But when people read the source and try to understand how it works they might also want to take some notes. One could transform these notes in documentation comments. This is just an idea. I didn't try that out - it could be that documenting the kernel that way may be harder than I think.
I'm glad to see that documentation is welcome.
Andi
_______________________________________________
Kernel-janitors mailing list
[email protected]
https://lists.osdl.org/mailman/listinfo/kernel-janitors
Quoted 7 lines · Randy Dunlap
On Fri, 13 Oct 2006 19:53:05 +0200 Andi Drebes wrote:
In general, yes, we want/need more documentation.
Caveat: don't document obvious things like:i++; /* increment the array index */
Quoted 9 lines
It's more important to document why something is done and generally how it is done. "What" is important, but could easily be one or two sentences, while the why and how may take much more.
It's not clear to me that this is a good kernel-janitors project, but I don't want to discourage anyone either. However, I've tried documenting some parts of the kernel code and it's fairly difficult to do so in lots of places, unless you are very familiar with the code.
As I've been putting .5 hours/day into reading the LKML and LWN etc., what I really want to see is
a) A better documented object model. Something doxygen-esque pulled out of the kernel headers would be teh r0x0rz, particularly if the output reflected obviously the .config used against that particular run
b) More clear peripheral tool documentation. Kbuild has some good stuff, but try this experiment: get someone who has, say, run a Gentoo system (i.e. knows their way around a command line) and say, "Build me the latest -mm kernel" and watch them not have a smooth experience.
c) A little more coherence on the LKML. I'm not at the point of trying to pluck patches and try them out, but I wouldn't even really want to try. The organization scheme for the kernel community is rather mystical. ;)
My point is that the current situation filters out all but the hardiest. Maybe I'm just a little slow, and maybe keeping out the riff-raff is rather a feature. A little more OLS and maybe that Linux Lunacy Cruise next summer will help. You really have to want to do this kernel stuff.
Signature · 6 lines
Christopher Smith Pursuer of knowledge _______________________________________________ Kernel-janitors mailing list [email protected] https://lists.osdl.org/mailman/listinfo/kernel-janitors
Quoted 18 lines · On Sun, 15 Oct 2006 11:27:36 -0400 Chris Smith wrote:
Quoted 7 lines · Randy Dunlap
On Fri, 13 Oct 2006 19:53:05 +0200 Andi Drebes wrote:
In general, yes, we want/need more documentation.
Caveat: don't document obvious things like:i++; /* increment the array index */
Quoted 9 lines
It's more important to document why something is done and generally how it is done. "What" is important, but could easily be one or two sentences, while the why and how may take much more.
It's not clear to me that this is a good kernel-janitors project, but I don't want to discourage anyone either. However, I've tried documenting some parts of the kernel code and it's fairly difficult to do so in lots of places, unless you are very familiar with the code.
Quoted 10 lines
As I've been putting .5 hours/day into reading the LKML and LWN etc., what I really want to see is
a) A better documented object model. Something doxygen-esque pulled out of the kernel headers would be teh r0x0rz, particularly if the output reflected obviously the .config used against that particular run
b) More clear peripheral tool documentation.Kbuildhas some good stuff, but try this experiment: get someone who has, say, run a Gentoo system (i.e. knows their way around a command line) and say, "Build me the latest -mm kernel" and watch them not have a smooth experience.
Not knowing anything about gentoo, is that a gentoo-specific "problem"? AFAIK, anyone can use ketchup or the script that I use (http://www.xenotime.net/linux/scripts/grab-kernel-rc)
to grab any specified -mm or mainline kernel (with or without -rcN or -mmN or -gitN) with ease. So is it a build problem? Oh, something to do with the gentoo sandbox?
Quoted 4 lines
c) A little more coherence on the LKML. I'm not at the point of trying to pluck patches and try them out, but I wouldn't even really want to try. The organization scheme for the kernel community is rather mystical. ;)
LKML is overused and abused IMO. I'd prefer to see usb stuff on the usb mailing lists, ATA stuff on linux-ide, memory mgt stuff on linux-mm, SCSI on linux-scsi, etc etc etc.... for development work. For user bug reports, I think that having one mailing list is a good idea, such as lkml, or using bugzilla.kernel.org.
Quoted 5 lines
My point is that the current situation filters out all but the hardiest. Maybe I'm just a little slow, and maybe keeping out the riff-raff is rather a feature. A little more OLS and maybe that Linux Lunacy Cruise next summer will help. You really have to want to do this kernel stuff.
I easily agree with the latter part.
---
~Randy
_______________________________________________
Kernel-janitors mailing list
[email protected]
https://lists.osdl.org/mailman/listinfo/kernel-janitors
Quoted 12 lines · Chris Smith
Quoted 11 lines · Randy Dunlap
On Fri, 13 Oct 2006 19:53:05 +0200 Andi Drebes wrote:
In general, yes, we want/need more documentation.
Caveat: don't document obvious things like:i++; /* increment the array index */
It's more important to document why something is done and generally how it is done. "What" is important, but could easily be one or two sentences, while the why and how may take much more.
Quoted 8 lines
Quoted 5 lines
It's not clear to me that this is a good kernel-janitors project, but I don't want to discourage anyone either. However, I've tried documenting some parts of the kernel code and it's fairly difficult to do so in lots of places, unless you are very familiar with the code.
As I've been putting .5 hours/day into reading the LKML and LWN etc., what I really want to see is
TBH, 30 minutes a day isn't going to cut it, unless you're just treading subject lines on LKML (and even then, only on low-volume days).
Quoted 4 lines
a) A better documented object model. Something doxygen-esque pulled out of the kernel headers would be teh r0x0rz, particularly if the output reflected obviously the .config used against that particular run
There is the source, after all (which was the start of this thread, more comments in the source). And various files in Documentation/driver-model, which is probably the most developed-as-an-object-model object-model that I can think of in the kernel right now.
I'm not sure, though, what you want documented in a).
Quoted 4 lines
b) More clear peripheral tool documentation.
Kbuildhas some good stuff, but try this experiment: get someone who has, say, run a Gentoo system (i.e. knows their way around a command line) and say, "Build me the latest -mm kernel" and watch them not have a smooth experience.
There is Documentation/applying-patches.txt, as well as the tools that Randy mentioned. Gentoo user != kernel developer, btw.
Quoted 4 lines
c) A little more coherence on the LKML. I'm not at the point of trying to pluck patches and try them out, but I wouldn't even really want to try. The organization scheme for the kernel community is rather mystical. ;)
It works for most :) Yes, as Randy said separately, it would be nice if devlopment discussions stuck to the appropriate list, but there is sufficient (and sometimes necessary) cross-development that often things spillover.
As far as plucking patches go, it requires some finesse, but that's what the tools are for: git, mercurial and quilt, to name a few (there's also akpm's patch-scripts, which quilt is based on).
Quoted 5 lines
My point is that the current situation filters out all but the hardiest. Maybe I'm just a little slow, and maybe keeping out the riff-raff is rather a feature. A little more OLS and maybe that Linux Lunacy Cruise next summer will help. You really have to want to do this kernel stuff.
Yes, and if you want do more than lurk, then you probably need to dedicate yourself to one subsystem for a while, unless you're someone like Andrew or Randy, who are able to keep tabs on multiple things at the same time (in Andrew's case, way more than I ever though possible).
Thanks,
Nish
Signature · 6 lines
Nishanth Aravamudan <[email protected]> IBM Linux Technology Center _______________________________________________ Kernel-janitors mailing list [email protected] https://lists.osdl.org/mailman/listinfo/kernel-janitors
Quoted 6 lines · Nishanth Aravamudan
Quoted 2 lines
As I've been putting .5 hours/day into reading the LKML and LWN etc., what I really want to see is
TBH, 30 minutes a day isn't going to cut it, unless you're just treading subject lines on LKML (and even then, only on low-volume days).
Absolutely, I have been skimming. Just understanding the various version control systems seems to be time-consuming. I've acquired and booted the latest -mm via mercurial and quilt, but git has eluded me thus far.
Quoted 5 lines
Quoted 4 lines
a) A better documented object model. Something doxygen-esque pulled out of the kernel headers would be teh r0x0rz, particularly if the output reflected obviously the .config used against that particular run
Quoted 8 lines
There is the source, after all (which was the start of this thread, more comments in the source). And various files in
Documentation/driver-model, which is probably the most developed-as-an-object-model object-model that I can think of in the kernel right now.I'm not sure, though, what you want documented in a).
A really discoverable model would be something along the lines of javadoc. Some of my best learning comes from simply browsing about in such. Certainly the source is the ultimate, but it would also be nice to produce documentation filtered via the .config, so that undesired options and platform-specific items are omitted.
This would especially help the n00b.
I say these things knowing that the best way to attack the itch is scratch it. ;)
Quoted 8 lines
Quoted 4 lines
b) More clear peripheral tool documentation.
Kbuildhas some good stuff, but try this experiment: get someone who has, say, run a Gentoo system (i.e. knows their way around a command line) and say, "Build me the latest -mm kernel" and watch them not have a smooth experience.There is
Documentation/applying-patches.txt, as well as the tools that Randy mentioned. Gentoo user != kernel developer, btw.
Certainly. Wasn't meaning to evangelize Gentoo there, just offer a rough skill gauge. An earlier draft of the post said "someone who has completed a linuxfromscratch.org project"
Quoted 5 lines
Quoted 4 lines
c) A little more coherence on the LKML. I'm not at the point of trying to pluck patches and try them out, but I wouldn't even really want to try. The organization scheme for the kernel community is rather mystical. ;)
Quoted 9 lines
It works for most :) Yes, as Randy said separately, it would be nice if devlopment discussions stuck to the appropriate list, but there is sufficient (and sometimes necessary) cross-development that often things spillover.
As far as plucking patches go, it requires some finesse, but that's what the tools are for: git, mercurial and quilt, to name a few (there's also akpm's patch-scripts, which quilt is based on).
Worked examples, while tedious to produce, would help. As above, I say this realizing that I need to Just Do It (and then post the worked example).
Quoted 11 lines
Quoted 5 lines
My point is that the current situation filters out all but the hardiest. Maybe I'm just a little slow, and maybe keeping out the riff-raff is rather a feature. A little more OLS and maybe that Linux Lunacy Cruise next summer will help. You really have to want to do this kernel stuff.
Yes, and if you want do more than lurk, then you probably need to dedicate yourself to one subsystem for a while, unless you're someone like Andrew or Randy, who are able to keep tabs on multiple things at the same time (in Andrew's case, way more than I ever though possible).
Still making measured progress soaking the general stuff. The lovely thing about FOSS is that you don't have a change in someones business model wiping out the equity in your time investments. It's all good, and I will get there. Thanks.
Signature · 6 lines
Christopher Smith Pursuer of knowledge _______________________________________________ Kernel-janitors mailing list [email protected] https://lists.osdl.org/mailman/listinfo/kernel-janitors