On Tue, 21 Oct 2008, Felipe Monteiro de Carvalho wrote:
> On Tue, Oct 21, 2008 at 10:45 AM, Marco van de Voort <[EMAIL PROTECTED]> > wrote: > > I already noticed, yes. Can you choose between in and out of source > > documentation with Doc-O-Matic, or is it always in source? > > It supports out of source documentation, but not in the Express (zero > cost) edition: > > http://www.doc-o-matic.com/featurematrix.html > > > I'm not that fond of in-source docs. It has a certain principal appeal > > (maintaining both together), but I don't like the practice. Or at least the > > ones that I have seen. > > I find that the external documentation imposes a too big overhead. > When in-source I can write it in the same editor I am used to, > navigating the same source I am used to, instead of an external > representation of it. Not to mention when things get renamed external > docs usually have a hard time. > > The external documentation duplicates information, because we already > describe how things work in the comments, and then we need to describe > that again in external docs. Or if we don't comment properly it > becomes hard to underderstand the code. Comments in source are generally limited to one or 2 lines. This is OK for docs that only you yourself need. API Documentation for externals should extensively describe how something works, describing possible pitfalls and whatnot. The sources would become totally unreadable if you would mix them with the current documentation. Michael. _______________________________________________ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal
