Eur van Andel wrote:
> On 24 Oct 2008, at 20:06 , Rob Hamerling wrote:
>> Some doc (either separate or as comment in the library) should inform
>> the user about everything the library can do. It should explain the
>> functionality of each procedure, the meaning and possible/allowed
>> values
>> of the various external constants and variables, and the limitations.
>> Providing the complete information ('reference manual') allows him to
>> *learn* all by himself how to explore the possibilities of the library
>> for his specific needs.
>
> An actual program is always better than any documentation. I've seen
> countless "examples" of code THAT DO NOT COMPILE. We should never do
> this.
From which of my words do you conclude that I suggest we must publish
uncompilable samples? You may have your opinion about anything, but do
not couple that to a completely unrelated text!
I repeat: libraries should be fully documented, and that means for many
libraries much more than providing the most elementary sample. It could
be in a separate document, as comment in the source of the library, or
in a complete sample program where every aspect of the library it
covered. I don't care, as long as it makes it possible for a user to
explore the library to his needs.
Regards, Rob.
--
Rob Hamerling, Vianen, NL (http://www.robh.nl/)
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en
-~----------~----~----~----~------~----~------~--~---
