I would agree with this. Code comments should not contain large scale
documentation for a number of reasons:
1. If the coder or documenter wants to update their code, they cannot
do so seperately, it would have to be coordinated a lot. Linus
should not have to handle integrating all the documentation, he has
enough to do with the code.
2. Documentation will always be a little out of sync, anyone who
experiments a lot with code knows you can't keep it up to date
for each tweak. If it is in a seperate file, it can be kept
coordinated and also versioning would be seperate.
3. Obvious kernel tarball size arguments. (Imagine the traffic..)
Likewise there should be a seperate discussion list.
..i could go on..
>But,
>
>1. WE NEED A KIND OF STYLE GUIDE FOR DOCUMENTATION!
The documentation could probably be laid out in a format similar to
the layout of the kernel. That way if you want to document something
you know immediately if it is documented. There would be other files
which would give general info, overviews, etc.
Probably something like:
Table of contents
(one line about each function/structure defined).
Overview:
Context: Talk about relevant hardware, compile options.
Notes: How this file differs from the general case.
Function1:
Kernel version it was based on.
What it is (briefly).
Describe it's operation relative to other functions of
the same type (i.e. how is it different from the general case.)
Bugs/limitations
Notes
Function2:
(likewise)
I mention the general case. I think there should be a file that
describes each standard interface. For example, the standard
functions used by a character special device.
In each major directory there should also probably be a "glossary",
i.e. in the "net" directory it might include a definition of and
explanation of "skbuff".
I would be willing to maintain the files, although I don't have enough
knowledge yet to actually write most if any of them.
If this is to be done there needs to be a seperate list for it, or at
least an understanding not to discuss it (much if any) here.
--kmb203@psu.edu----------------Debian/GNU--1.3---Linux--2.0.30---
To A Quick Young Fox:
Why jog exquisite bulk, fond crazy vamp,
Daft buxom jonquil, zephyr's gawky vice?
Guy fed by work, quiz Jove's xanthic lamp --
Zow! Qualms by deja vu gyp fox-kin thrice.
-- Lazy Dog