[pmwiki-users] generated documentation available
Joachim Durchholz
jo at durchholz.org
Sat Jul 9 16:24:11 CDT 2005
Patrick R. Michaud wrote:
>
> I also have a question about the level of detail we should be putting
> into the code documentation. For example, I noticed that the
> stripmagic() function is currently undocumented, but fully explaining
> it and its purpose could easily take a paragraph or two, which
> would be several times larger than the function itself! Any thoughts
> about what we might want to do here?
Bite it and document the thing. It's fully OK if the docs for a function
are longer than the function itself.
The only thing I'd actively consider is that the PmWiki release process
could be extended by a pass that strips the comments from the sources.
That would shorten the sources somewhat and might help with the
execution latencies.
On the other hand, the speed effect is probably negligible and it's
complicating things for programmers, so there's probably no net gain.
> Is there a way that we could
> put things in the pmwiki comments that doxygen could then turn into
> links to fuller documentation on pmwiki.org ?
Most likely.
I'd still recommend putting the full docs into the source. If a function
changes, the programmer will immediately see whether the docs need an
update; if it's a separate place, the docs will quickly become outdated
and (as you correctly noted elsewhere) wrong docs are worse than no docs
at all.
I have worked with systems that keep the docs in-line with the
functions, and offer separate tools for extracting the docs for
convenient viewing. My experience was invariably that the docs were more
concise, more to the point, more accurate, more timely updated, and
(last but not least) more fun to write.
Regards,
Jo
More information about the pmwiki-users
mailing list