Kernel Development Documentation?
I was reading an article today on Slashdot about how poorly documented the Windows API was and had this fear that Linux could get the same way. So, cut to the point:
Is there a project underway that documents how things like the VM, the Memory Manger, what a a specific driver needs to do, what it needs to return, how it is called, what do all those files in arch/whatever do? Are there bits and pieces spewed around all over the net? It would seem to me that someone ( and I will volunteer ) sould sit down and put together some sort of documentation system for the Kernel. Somthing to the effect of a super help for users with all the technical details for developers.
Obviously it should be kept on the Internet but in such a way that it can be contributed to by many people ( preferrably the people who have influence with the code ). It should also have a team of "editors" and be maintained such that it is browsable, printable, and publishable.
I personally feel that now would be the time to do this while the current development tree is being wrapped up for production and there is no major work on a 2.5 development tree - at least publicly. Like I said, I voulenteer to coordinate this effort and find a place to host it. What are the thoughts of others? Good idea, bad idea? Input is more than welcome.
Signature · 11 lines
-Carl Perry [email protected] "Real programmers don't draw flowcharts. Flowcharts are, after all, the illiterate's form of documentation. Cavemen drew flowcharts; look how much good it did them." -Fortune (The App, not the Magazine) - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected] Please read the FAQ at http://www.tux.org/lkml/
Quoted 4 lines · Carl Perry
I was reading an article today on Slashdot about how poorly documented the Windows API was and had this fear that Linux could get the same way. So, cut to the point:
Whoever posted this on Slashdot is smoking some killer dope or something. The Windows API is very well documented via online docs from
MSDN -- better than most software anywhere in the world. Whoever said
this was high or something or ignorant or never had an MSDN subscription. I used to get 20-40 CD's a month from MS on a Universal Subscription, with enormous documentation..
Jeff
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 3 lines
Is there a project underway that documents how things like the VM, the Memory Manger, what a a specific driver needs to do, what it needs to return, how it is called, what do all those files in
arch/whateverdo? Are there bits and pieces
For the kernel stuff there is a project to put documentation about functions and what they do inline into the kernel. Its slow progress. Trying to do anything formal and structured isnt going to be productive until the documentation is much much more complete
For syscalls Andries Brouwer maintains a man page collection (and writes many of them). He takes submissions.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 3 lines · Alan Cox
Quoted 3 lines
Is there a project underway that documents how things like the VM, the Memory Manger, what a a specific driver needs to do, what it needs to return, how it is called, what do all those files in
arch/whateverdo? Are there bits and pieces
Of course we are not really talking Linux api here - these are internal interfaces. The Linux syscalls themselves are reasonably well-documented. The internal interfaces... weeelllll...
I know exactly how it feels when first getting into the internal kernel interfaces - for me that was barely a year ago. I wanted at that time to try and fix all the documentation problems as I went, but it quickly turned into a choice between doing useful development and doing useful documentation. Guess which one I chose. I sincerely hope that others will make the opposite choice, and the linux hacking world will be a better place.
Quoted 7 lines
For the kernel stuff there is a project to put documentation about functions and what they do inline into the kernel. Its slow progress. Trying to do anything formal and structured isnt going to be productive until the documentation is much much more complete
For syscalls Andries Brouwer maintains a man page collection (and writes many of them). He takes submissions.
http://www.win.tue.nl/math/dw/personalpages/aeb/linux/
Wow, that's useful. Also check out:
http://kernelnewbies.org/links/
with many high quality links to kernel documentation around the web.
Tigran Aivazian has been preparing 'Linux Kernel Internals' which is *highly recommended* and 100% free. Why don't you get together with him, and Gary Lawrence Murphy (see his monthy kernel wiki nag)?
Personally, I try to do the right thing and submit at least one piece of documentation per month to somebody's documenation project but... it's not always so easy to free up the required hour or two. This month my feeble attempt consisted of nagging Ben LaHaise to submit a particularly lucid email he sent me as a code comment.
Maybe next month will be better.
Signature · 5 lines
Daniel - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected] Please read the FAQ at http://www.tux.org/lkml/
Quoted 2 lines · Daniel Phillips
Tigran Aivazian has been preparing 'Linux Kernel Internals' which is *highly recommended* and 100% free.
in case he is curious where to find it:
http://www.moses.uklinux.net/patches/lki.html
(or .sgml for master source).
Interestingly, the main problem with LKI turned out to be _not_ the issue of keeping it uptodate but filling in the missing bits, most notably buffer cache and page cache. By now I more or less actually understand the Linux buffer cache (only after diligent comparison with UW7, AIX, OSR5 and many other commercial UNIX implementations whose source code is available) but still not the page cache (even after reading everything about it that I could find, including recent Understanding Linux Kernel book by Bovet which I just finished reading). E.g. it is not even obvious to me that things will get any worse if one throws away the entire readahead logic from the page cache.
So, if someone wants to write a chapter on Linux page cache and contribute it to the LKI book (and thus become a co-author :) please feel free -- it will be a proof that someone in the world actually understands it -- at the moment I doubt that very much... Take it as a challenge :)
Regards,
Tigran
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 10 lines · Daniel Phillips
Quoted 4 lines · Alan Cox
For the kernel stuff there is a project to put documentation about functions and what they do inline into the kernel. Its slow progress. Trying to do anything formal and structured isnt going to be productive until the documentation is much much more complete
Tigran Aivazian has been preparing 'Linux Kernel Internals' which is *highly recommended* and 100% free. Why don't you get together with him, and Gary Lawrence Murphy (see his monthy kernel wiki nag)?
Quoted 5 lines
Personally, I try to do the right thing and submit at least one piece of documentation per month to somebody's documenation project but... it's not always so easy to free up the required hour or two. This month my feeble attempt consisted of nagging Ben LaHaise to submit a particularly lucid email he sent me as a code comment.
Lucid e-mails often get stuck into Documentation/*, that's fine.
The preferred is 'make {pdf,ps,html}docs' as yanked from Documentation/DocBook.
Jeff
Signature · 7 lines
Jeff Garzik | Building 1024 | These are not the J's you're lookin' for. MandrakeSoft | It's an old Jedi mind trick. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected] Please read the FAQ at http://www.tux.org/lkml/