Messages in this thread | | | From | Larry McVoy <> | Date | Sun, 26 Sep 1999 20:23:15 -0700 | Subject | Documentation / API thread |
| |
I've been following this code / documentation thread for a while.
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/
| |