> I have no problem with that for how the source code works.
>
> I would object to something like storing RFC822 as comments inside your
> SMTP implementation.

Yeah, that's really not very appropriate.

>> On the other hand, your source code is now littered with miles of text
>> which
>> have nothing to do with the compiler error you're now getting...
>
> Which also forces a recompile every time you change it, and means anyone
> writing (or reading) technical documentation has to have access to the
> code, potentially breaking stuff when they accidentally modify the file.

I think we can perhaps summarise this:

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.

As an aside, everyone in the Haskell world seems to document their stuff 
using a tool called Haddock. Like Java's docgen (and presumably a 
bazillion similar tools), it takes source code comments and builds an 
API reference from it.

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...

Post a reply to this message