[pmwiki-users] generated documentation available

Crisses crisses at kinhost.org
Sat Jul 9 17:28:22 CDT 2005


On Jul 9, 2005, at 5:24 PM, Joachim Durchholz wrote:

> Bite it and document the thing. It's fully OK if the docs for a  
> function are longer than the function itself.

Yeah -- that only means the function is exceptionally well written  
and/or versitile -- both of which commend the programmer ;)

I think a link back to the wiki is important, though, because then  
people who never touch the code itself get to comment, expand on  
usage, and contribute.  And check our spelling ;)

> 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.

Oh dear -- this only works for me (the stripped downloads) if  
developers have easy access to the comment-riddled code :)

> 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.

This is true.

Doxygen can create man pages (further making pmwiki eligible as an  
rpm or deb package), LaTeX, and xml from the comments.  If absolutely  
needed, there might be some way to get PmWiki pages to pluck the  
comments out (like includes) from xml documentation and put them in  
the wiki page.  *shrugs*.

> 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.

I have a much easier time documenting code as I write, or when it  
works, directly in the program code than I would to remember to log  
in elsewhere and write documentation.

Because it didn't matter as much for me to document my pmwiki  
cookbook code as carefully as my Cookbook/PageName, I didn't do it as  
well as I should have -- I should link my cookbook module to the  
pmwiki page that explains all the functions and options.

Crisses
----
"...and then I found out that he is as pen-obsessed as I am...and  
that he even uses the same make & model of pen that I do.  Right  
then, I knew he was the man of my dreams and I could stop looking..."
   (conversation in my own head)




More information about the pmwiki-users mailing list