[pmwiki-users] generated documentation available
Patrick R. Michaud
pmichaud at pobox.com
Sat Jul 9 09:22:01 CDT 2005
On Sat, Jul 09, 2005 at 08:41:32AM -0400, Crisses wrote:
> I'm not sure I like the frame sidebar that I generated the last
> time :) But it shows one of the many options that can be generated.
I'm not sure I like the frame sidebar either, but I'm not sure I
want to get rid of it either. I seem to be in an uncertain mood
this morning... :-|
> I don't
> know if I would recommend including uploads/ -- it will still go over
> the cookbook recipes.
I think I'd recommend against including uploads/, at least for the
standard docs. It might catch some of the .php scripts, but it
probably won't (and shouldn't) find things that are in zip/tgz
archives, and there are some scripts that have multiple versions
in uploads/ and I suspect that could get very confusing quickly.
Or, we could generate two doxygen outputs -- one that is just the
standard PmWiki distribution and one that includes uploads/ and
the full Cookbook. I think I like that approach.
I also notice that doxygen is having trouble parsing certain constructs
in PmWiki. See, for example, the documentation of Cells()
at http://www.kinhost.org/wikidocs/stdmarkup_8php.html#a1 --
it loses track of the quotes and incorrectly reports that
Cells() references Keep(), Markup(), and PSS().
Also, I find the call graph images to be too shallow to
be terribly useful (besides being misleading, which in the case of
documentation is worse than none).
But on the whole, this looks very promising!
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? 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 ?
More information about the pmwiki-users