Orchid XP v8 wrote:
>>> Well now, there are basically two ways to do documentation:
>>
>> You already lost. If you're not documenting things that have no place 
>> in the source code to put the documentation, you've already failed at 
>> documenting your system.
> 
> That too.
> 
> I'm thinking about documenting a library API,

It's fine for the details. But try to document (say) the BSD interface to 
TCP by documenting only the listen(), accept(), bind(), and connect() calls. 
Without understanding what an IP address is, or a socket, or how DNS works, 
etc you're still not going to win.

Or take something like a big windowing system, or a 3D graphics system, or a 
physics library, and try to document *just* the routines without documenting 
the architecture of the system.  You'll spend three days trying to find out 
where to start reading the documentation.

-- 
   Darren New, San Diego CA, USA (PST)
   I ordered stamps from Zazzle that read "Place Stamp Here".

Post a reply to this message