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.
xsdocparse
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
All xsubs and pod from here until the next object directive or MODULE line will be placed under the key 'Package::Name' in xsdocparse's data structure. Everything from this line to the next =cut is included as a description POD.
This causes xsdoc2pod to call 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.
podify_values
Paragraphs of this type document xsubs, and are associated with the xsubs by xsdocparse.pl. If the full symbol name is not included, the paragraph must be attached to the xsub declaration (no blank lines between =cut and the xsub).
Within the apidoc PODs, we recognize a few special directives (the "for\s+" is optional on these):
Override the generated call signature with the ... text. If you include multiple signature directives, they will all be used. This is handy when you want to change the return type or list different ways to invoke an overloaded method, like this:
=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 */
The arg directive adds or overrides an argument description. The description text is optional, as is the type specification (the part in parentheses). The arg name does not need to include a sigil, as dollar signs will be added. FIXME what about @ for lists?
Given a $datafile containing the output of xsdocparse.pl, create in $outdir a pod file for each package, containing everything we can think of for that module. Output is controlled by the =for object directives and such in the source code.
=for object
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.
Pretty-print the object properties owned by the Glib::Object derivative $packagename and return the text as a string. Returns undef if there are no properties or $package is not a Glib::Object.
List and pretty-print the values of the GEnum or GFlags type $packagename, and return the text as a string. Returns undef if $packagename isn't an enum or flags type.
Query, list, and pretty-print the signals associated with $packagename. Returns the text as a string, or undef if there are no signals or $packagename is not a Glib::Object derivative.
Pretty-prints the ancestry of $packagename from the Glib type system's point of view. This uses Glib::Type->list_ancestors; see that function's docs for an explanation of why that's different from looking at @ISA.
Returns the new text as a string, or undef if $packagename is not a registered GType.
Pretty-print the list of GInterfaces that $packagename implements. Returns the text as a string, or undef if the type implements no interfaces.
Call xsub_to_pod on all the xsubs under the key $packagename in the data extracted by xsdocparse.pl.
xsub_to_pod
Returns the new text as a string, or undef if there are no xsubs in $packagename.
Convert a C type name to a Perl type name.
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.
Convert an xsub hash into a string of pod describing it. Includes the call signature, argument listing, and description, honoring special switches in the description pod (arg and signature overrides).
Given an xsub hash, return a string with the call signature for that xsub.
Prepend a $ to anything that's not the literal ellipsis string '...'.
Mangle default parameter values from C to Perl values. Mostly, this does NULL => undef.
C type to Perl type conversion for argument types.
C type to Perl type conversion suitable for return types.
Glib::ParseXSDoc
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 2003 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
To install Glib, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Glib
CPAN shell
perl -MCPAN -e shell install Glib
For more information on module installation, please visit the detailed CPAN module installation guide.