On Apr 14, 2005, at 2:10 PM, Tassilo von Parseval wrote:
Not really XS-related: I probably wouldn't generate the PODs dynamically
at install-time. The problem is that people can't get an idea of the API
of the module when by around search.cpan.org. For me, the module's
documentation is the main criterion for trying out or not trying out a
new module.
What he was doing here was just using the infrastructure we invented for gtk2-perl, where there are simply too many xsubs for hand-maintained documentation to be practical. The tools in Glib::ParseXSDoc and Glib::GenDoc parse your xs files for xsub signatures and match them up with a special dialect of pod comments, so that your xsubs get mentioned in the docs whether you wrote something about them or not. Also, a fair amount of information (inheritance hierarchy, object property types, signal signatures, enumeration values) is gleaned through introspection, so you actually have to build and run the bindings in order to create the docs.
And, yes, it does irk me that although we put all that work into documentation generation, which creates over 200 manpages for the Gtk2 extension alone, the gtk2-perl extensions look almost completely undocumented on CPAN. As a workaround, we have the docs online at http://gtk2-perl.sourceforge.net/doc/pod/ .
The obvious solution is to pregenerate the pod and include the generated files in the dist tarball, but a) there's the chicken and egg problem of having to build before you can build the dist, and b) where in the tarball do you put the *.pod files such that CPAN will see them?
(Any suggestions welcome.)
--
I don't like... this game... when there's cannons... being shot... at me.
-- Elysse
