On Sun, 4 Jun 2006, Thor Lancelot Simon wrote:

> Unfortunately, often the only easy way to give an adequate explanation of
> "what does this API" do -- when "how long does it take/how much memory
> does it use" are considered part of what it "does", which for code like
> sorting or hashing code it's simply insane not to -- is to answer the
> question of "how it works".  This, in fact, is exactly such a case.

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 should 
not leak many of the details of the implementation, because it makes it 
harder to change the underlying implementation.

That aside though, even if your interface does imply a specific 
implementation (that is, you cant make use of it without knowing the 
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.

The documentation can then give interface details, and the location of the 
implementation. I'm not sure what the downside to this would be. My 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. That 
said, flawed possibly inaccurate documentation trumps no documentation.