I remember a discussion a while back in this regard, with various
useful suggestions, among which were standard assertions which
documented when a routine was assuming that various smp locks were
held (and oopsed if called without locks held).
Are there any plans to put this stuff into place (perhaps in 2.5?). I
would be happy to help in the grunt work of adding them.
Sean
On Sun, Sep 26, 1999 at 08:23:15PM -0700, Larry McVoy wrote:
> 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/
>
-
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/