> On 26 Sep 1999, Nat Lanza wrote:
> > David Hinds <dhinds@zen.stanford.edu> writes:
> >
> > > One suggestion would be to have a set of man pages included in the
> > > kernel tree. And try to make them sufficiently useful that people
> > > would want to keep them up to date. In this case, I think adding to
> > > the kernel tree would be a good thing, because it keeps the
> > > documentation in the same place as what it is documenting. I'd be
> > > willing to write man pages for a few things myself. The current
> > > documentation in the kernel tree is a bit too informal and incomplete.
>
> The GNOME project uses the 'gnome-doc' tool to process specially-marked
> comments in the actual source code, and generates info, HTML, docbook,
> man pages, or text files as output. I've often thought about suggesting
> the import of that tool into the kernel tree as scripts/kernel-doc.
>
> How does that sound? Using a tool which takes comments from the actual
> source code increases the likelihood that the documentation will be
> up-to-date.
Some problems with documentation:
- is a poor substitute for code
- can never be complete, accurate, or timely enough to match the source
- <language> is much more ambiguous than C
- encourages bad habits
- developers substitute docs for readable code
- people read the documentation and fear the code
- when people do read the code, they interpret it as suggested by the
documentation, missing subtle and not so subtle bugs
- fewer people understand the actual code
- adds more inertia to the interfaces of a system
- means changes require a greater investment of effort
- implicitly promises things won't get changed
- broken designs stay broken longer
- is a lot of work
- and we've been doing pretty damn well without it
- and there are good reasons to think it's a hindrance
- and there are more important/interesting things to do
- and you don't get very far telling volunteers to do things they don't
want to
- and other people who are motivated in that direction can do it
I think the informal commentary style of things like
Documentation/exceptions.txt is far preferable to any sort of formal
function-by-function docs, inline or otherwise.
-- "Love the dolphins," she advised him. "Write by W.A.S.T.E.."
- 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/