in reply to The sourcecode *is* the documentation, isn't it?

These points are true of almost any documentation system.

the author of this demo code does not use POD, perhaps because he is sick of having to use a different documentation system for each prog language, and instead uses this same style for every environment

IMHO, the actual implementation of such a system will vary so widely between languages that you might as well learn the language-specific documentation system anyway.

should the author be persecuted for not using POD?

Yes.

is there really any such thing as 'self-documenting' code?

Code which is programmed specifically for clarity. This might be a Holy Grail which is never reached, but at least we can better ourselves while trying to reach it. As a last resort, we have comments.

does anyone out there really care about this stuff at all?

Not really. Classes need their complete public interface to be documented, because someone shouldn't have to read the raw source code to understand how something works. Other than that, code documentation is really only needed when something tricky or non-obvious is going on.

----
send money to your kernel via the boot loader.. This and more wisdom available from Markov Hardburn.

  • Comment on Re: The sourcecode *is* the documentation, isn't it?