| Next: Glib::index | Previous: Glib::Flags | [Gtk2-Perl - Table of Contents] | [Gtk2-Perl - Index] |
Glib::GenPod - POD generation utilities for Glib-based modules
use Glib::GenPod;
# use the defaults:
xsdoc2pod ($xsdocparse_output_file, $destination_dir);
# or take matters into your own hands
require $xsdocparse_output_file;
foreach my $package (sort keys %$data) {
print "=head1 NAME\n\n$package\n\n";
print "=head1 METHODS\n\n" . podify_methods ($package) . "\n\n";
}
This module includes several utilities for creating pod for xs-based Perl modules which build on the Glib module's foundations. The most important bits are the logic to convert the data structures created by xsdocparse.pl to describe xsubs and pods into method docs, with call signatures and argument descriptions, and converting C type names into Perl type names. The rest of the module is mostly boiler-plate code to format and pretty-print information that may be queried from the Glib type system.
To make life easy for module maintainers, we also include a do-it-all function, xsdoc2pod(), which does pretty much everything for you. All of the pieces it uses are publically usable, so you can do whatever you like if you don't like the default output.
All of the information used as input to the methods included here comes from
the XS files of your project, and is extracted by Glib::ParseXSDoc's
xsdocparse. This function creates an file containing Perl code that may be
eval'd or require'd to recreate the parsed data structures, which are a list of
pods from the verbatim C portion of the XS file (the xs api docs), and a hash
of the remaining data, keyed by package name, and including the pods and xsubs
read from the rest of each XS file following the first MODULE line.
Several custom POD directives are recognized in the XSubs section. Note that
each one is sought as a paragraph starter, and must follow a =cut directive.
=cut is included as a
description POD.
=for object Gnome2::PanelApplet::main (Gnome2::PanelApplet) =cut
This will create Gnome2/PanelApplet/main.pod containing the automatically generated documentation for Gnome2::PanelApplet (hierarchy, signals, etc.) plus the method listing from the current XS file.
podify_values on Package::Name when
writing the pod for the current package (as set by an object directive or
MODULE line). Any text in this paragraph, to the next =cut, is included
in that section.
=cut and
the xsub).
Within the apidoc PODs, we recognize a few special directives (the "for\s+" is optional on these):
=for apidoc
=signature bool Class->foo
=signature ($thing, @other) = $object->foo ($it, $something)
Text in here is included in the generated documentation.
You can actually include signature and arg directives
at any point in this pod -- they are stripped after.
In fact, any pod is valid in here, until the =cut.
=cut
void foo (...)
PPCODE:
/* crazy code follows */
__hide__
as its type. The arg name does not need to include a sigil,
as dollar signs will be added. FIXME what about @ for lists?
Also, we honor a couple of "modifiers" on the =for apidoc line, following the symbol name, if present:
(These are actually handled by Glib::ParseXSDoc, but we list them here because, well, they're an important part of how you document the XS files.)
=for object directives
and such in the source code.
If you don't want each package to create a separate pod file, then use this function's code as a starting point for your own pretty-printer.
%basic_types used
for C type name to Perl package name mappings of types that are not registered
with the Glib type system. The file format is dead simple: blank lines are
ignored; /#.*$/ is stripped from each line as comments; the first token on
each line is considered to be a C type name, and the remaining tokens are the
description of that type. For example, a valid file may look like this:
# a couple of special types FooBar Foo::Bar Frob localized frobnicator
C type decorations such as "const" and "*" are implied (do not include them), and the _ornull variant is handled for you.
This function is called at all of the specified points through out the process of generating pod for a page. Any pod matching the position passed will be returned, undef if no matches were found. If position is undef all pods without sepcific postion information will be returned. pods is a reference to an array of pod hashes.
SYNOPSIS
After the NAME section
DESCRIPTION
After the SYNOPSIS section.
post_hierarchy
After the HIERARCHY section.
post_interfaces
After the INTERFACE section.
post_methods
After the METHODS section.
post_properties
After the PROPERTIES section.
post_signals
After the SIGNALS section.
post_enums
After the ENUMS AND FLAGS section.
SEE_ALSO
Replacing the autogenerated SEE ALSO section completely.
COPYRIGHT
Replacing the autogenerated COPYRIGHT section completely.
Returns the new text as a string, or undef if $packagename is not a registered GType.
xsub_to_pod on all the xsubs under the key $packagename in the
data extracted by xsdocparse.pl.
Returns the new text as a string, or undef if there are no xsubs in $packagename.
If no text has been set, we will attempt to create one for you, using what has been passed to set_year, set_authors, and set_main_mod. The year defaults to the current year, the authors default to 'The Gtk2-Perl Team', and the main mod is empty by default. You want the main mod to be set to the main module of your extension for the SEE ALSO section, and on the assumption that a decent license notice can be found in that module's doc, we point the reader there.
So, in general, you will want to specify at least one of these, so that you don't credit your work to us under the LGPL.
To set them do something similar to the following in the first part of your postamble section in Makefile.PL. All occurences of <br> in the copyright are replaced with newlines, to make it easier to put in a multi-line string.
POD_SET=Glib::GenPod::set_copyright(qq{Copyright 1999 team-foobar<br>LGPL});
Glib::MakeHelper::postamble_docs_full() does this sort of thing for you.
Uses %Glib::GenPod::basic_types to look for some known basic types, and uses Glib::Type->package_from_cname to look up the registered package corresponding to a C type name. If no suitable mapping can be found, this just returns the input string.
muppet bashed out the xsub signature generation in a few hours on a wednesday night when band practice was cancelled at the last minute; he and ross mcfarland hacked this module together via irc and email over the next few days.
Copyright (C) 2003-2004 by the gtk2-perl team
This library is free software; you can redistribute it and/or modify it under the terms of the Lesser General Public License (LGPL). For more information, see http://www.fsf.org/licenses/lgpl.txt