[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