On 4/21/2011 8:37, Invisible wrote:
> Embedding the API reference in the source code might be a good idea.
> Embedding the end-user documentation in the source code is a terrible idea.

Embedding overview-for-maintainers as comments distributed throughout the 
project is a bad idea.  Embedding code samples as comments in the source 
code is a bad idea. Embedding design decision discussions as comments is a 
bad idea.

> What it *doesn't* really let you do in a consistent way is write "this is
> WTF this project actually does and how it's structured" type documentation,
> which tends to be completely absent as a direct result...

That's precisely my point.

-- 
Darren New, San Diego CA, USA (PST)
   "Coding without comments is like
    driving without turn signals."

Post a reply to this message