brian@surge.insomnia.org wrote:
> The source already answers that question, though. Do you really think 
> it's a good idea to document things in multiple places? A good interface 
> ...
> underlying implementation), you STILL don't need to document it in a man 
> page, that's what the source code is for. If the implementation is 
> particularly complex, that source code should be commented, so atleast 
> if someone wants to change the implementation, they only have to modify 
> a single file.
> ...
> real fear here is that man pages will get written once and a few years 
> from now, will document an implementation that is no longer accurate. 

These are all worthy points. They remind me that (a) I left out the
SOURCE CODE REFERENCES section of the page (oops), and (b) I'd thought
seriously about adding a comment in the code saying "hey, this is
documented now, please update the man page if changed."

To the first question, I would answer, no, I'm no great fan of
documenting in multiple /places/, but I think there's a great value
in documenting multiple /ways/. The acceptable minimum ought to
be the code /and something else that isn't code/. It's a little like
the two spaces on a check, to write the amount in figures and longhand.
Some people write figures in both places, and it's especially easy for
them to write checks for the wrong amount: it's much easier to make the
same mistake twice than to make matching mistakes in two forms of
expression. What you're doing can become much more clear if every now
and then you're expected to SAY it.

Yes, if we had a thoroughly mature test-driven process where
everything is constantly put against tests written in advance,
you could make the argument that the "something else" is the test
code, but for now it isn't, and the best alternative is documentation.

To be clear, I /am/ only talking about exposed interface (which also
is the only part implicated in tests-as-docs). I completely agree
that true implementation internals are a different matter. Part of
the disagreement on this particular man page seems to be about which
details are interface and which are internal; I don't sense any
disagreement over the principle that the man page should cover interface.

It seems to me, though, that right now we are frequently trading off
on the side of making the programmer infer the interface by reading
the implementation. That's a difficult and dangerous inference task,
because you don't know how much of what you're reading is stable
interface, how much is implementation artifact, or even how much is
(dare I breathe the word) bug.  And if a lot of programmers go through
the same ordeal and write code based on their own inferences of what
the interface is, so that now you can't change anything without breaking
somebody's assumptions--why, that constrains your future implementation
choices at least as tightly as a thoroughly documented interface would.

To address the "multiple places" issue and the fear of docs going stale,
which is my fear too ... I think it would be swell to be able to make
man pages straight from doxygenesque stuff in the source; a more practical
step might be some kind of source comment that identifies a related
man page, and a cvs script that puts the commit log and the manpage name
on the queue of some daemon-with-eyeballs who can confirm that the
docs aren't now lying.

-Chap