Here's a few points for consideration:
1) Incorrect documentation is _far_ worse than no documentation.
2) Code gets updated, docs don't
3) Documenting interfaces is important, documenting implementation
is a great deal less important.
4) Terseness is good.
Given all that, you might consider documenting just the internal
interfaces and the semantics of those interfaces. For instance, what are
the interfaces to an inode? What are the semantics of those interfaces?
What's the locking model used from without the interface and from within
the interface (they are frequently different).
Diving into a ton of details about implementations specifics is going to
do nothing but clutter up the code. On the other hand, a set of docs
which defined the interfaces to the following set of kernel "objects"
would be something that a lot of people would use:
- files
- file systems
- block, char devices
- network devices
- scsi devices (and layers)
- processes
- sockets
- VM - both the VM address space and the page cache
That's probably an incomplete list but it's a good start. I personally
would love to see just the interfaces documented - I could care less
about the implementation - my experience is that the implementation
tends to change and the docs tend to get out of date (and hence
much worse than nothing because they are misleading). But interfaces
tend to live for a long time.
--lm
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/