[Geany-devel] Ann: GeanyGenDoc plugin

Colomban Wendling lists.ban at xxxxx
Fri Apr 16 01:16:05 UTC 2010


Hi everybody,

Some already know, or can remember, I started writing of a generic
documentation generator plugin a while ago [1]. And you know what? It
isn't dead, despite the appearances!

[next paragraph is a little story, you can skip it if you want to go to
the good directly]

Yes, it was more than one year ago. Here the little story...
I started then a plugin, gone ahead, but I soon found that the design
was terribly wrong: it was not extensible at all, and a nightmare both
to configure it correctly and to maintain it. So I started to find a
better design.
But in the meanwhile, I got other things to do, and so on - you probably
know what's it. And worst of all, my initial non-extensible, etc.,
plugin worked too well: I used it, despite its limitations, and the had
less personal need for a good implementation… and months passed.
Even so, I designed the new plugin, but saw that Geany's templates
wasn't powerful enough for what I needed (I needed loops, and wished
tests). Not a problem, I searched a template library, and as I didn't
find anyone, started to write my own [2]. And here goes another part of
the time.
But finally, I had it working well, and I could start the actual plugin.
 It was not so long ago, and finally, here we are: I've something
working, extensible, that should support every programming language that
Geany supports, and every documentation syntax the user can think of.

A little presentation of GeanyGenDoc:
GeanyGenDoc is a Genay plugin (really?) aiming to ease documenting the
code. Its goal is to automatically generate a documentation comment
(header) from any symbol (function, macro, structure, class, etc.) the
user want. I think it does most of the boring stuff: it can generates
almost everything that can be determined from the code. The only thing
left is to actually write the documentation.

Features:
 * Tagmanager-based symbols lookup, bringing (theoretical?) support for
every language supported by Geany's tagmanager;
 * User-defined template-based comments, allowing fine tuning on the
output documentation header;
 * Configuration-driven generation, allowing fine tuning on what should
be, and how it should be documented;
 * Per-language rules.

Of course it's young and needs testing and more; but as of my tests and
use, it work pretty well (at least for C and GtkDoc, haha).

If anyone would like to test, there is a temporary snapshot of the
current status: http://ban.free-h.net/geanygendoc/geanygendoc-0.1.tar.gz [3]

Hope it is useful for some, and I would really appreciated feedback!

Regards,
Colomban

[1] http://lists.uvena.de/pipermail/geany-devel/2009-February/000514.html
[2] http://ctpl.tuxfamily.org/
[3] One think I know missing is a correct documentation on how to
configure it. For now, I suggest to take a look at the default C
configuration, that use almost all the possible features. Also note the
comment at the top of src/ggd-file-type-loader.c, which while remaining
quite technical should be instructive.




More information about the Devel mailing list