I hope we can end this thread now, we had arguments for documenting the
kernel and we had arguments against it.
I decided to be on the side for documenting the kernel, if kernel cracks and
people who can read every code in 10 minutes (i am not worthy i am not
worthy... :) ) don't like docs - don't read this
I invite everyone to continue the discussion,
but we should keep this out of the kernel mailing list. So email me
or better someone sets up a mailing list.
---snip----- ONLY A EXAMPLE
Creating a linux Kernel documentation
This is a proposal for a RFC we should create for a kernel documentation
I believe this should be done, because before we happily write any kind
of documentation we should have documented it. You can send me your proposal
i will try to compose it to one RFC (email: s_dkling@student.uni-ulm.de).
(call it a Request for Comments makes me feel better because i really
want a discussion before we relabel it (HOWTO(?)) ).
1. I want to split this up in two kind of documentation
a) Inside Kernel Documentation
b) Outside Kernel Documentation
a) In my opinion every function should get at least one sentence
(so you don't need the big docu if you have a little understanding
if you take a quick look at some sources)
This information could be collected by javadoc
(proposed by Jauder Ho <jauderho@carumba.com>
b) Outside documentation
Structured in directories like the kernel tree
(proposed by Kevin M. Bealear <kmb203@psu.edu>
2. Tools to use
As we heard: javadoc
rcs for distributed enviroments
perl
Any proposals?
3. We need some volunteers which give us experience how this tools
work (maybe examples so that we get a glimpse, how it works)
(who did work for several years with documentation tools ?
+ and - i want to see here)
---snip--- THIS WAS ONLY A EXAMPLE
Dietmar