662 lines
17 KiB
HTML
662 lines
17 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Glib::GenPod</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Glib::GenPod</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-18<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Glib::GenPod - POD generation utilities for Glib-based modules
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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";
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
To make life easy for module maintainers, we also include a do-it-all function,
|
|
<B>xsdoc2pod()</B>, 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.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DOCUMENTING THE XS FILES</H2>
|
|
|
|
|
|
|
|
All of the information used as input to the methods included here comes from
|
|
the <FONT SIZE="-1">XS</FONT> files of your project, and is extracted by Glib::ParseXSDoc's
|
|
<TT>"xsdocparse"</TT>. 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 <FONT SIZE="-1">XS</FONT> 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 <FONT SIZE="-1">XS</FONT> file following the first <FONT SIZE="-1">MODULE</FONT> line.
|
|
<P>
|
|
|
|
Several custom <FONT SIZE="-1">POD</FONT> directives are recognized in the XSubs section. Note that
|
|
each one is sought as a paragraph starter, and must follow a <TT>"=cut"</TT> directive.
|
|
<DL COMPACT>
|
|
<DT id="1">=for object Package::Name<DD>
|
|
|
|
|
|
All xsubs and pod from here until the next object directive or <FONT SIZE="-1">MODULE</FONT> line
|
|
will be placed under the key '<I>Package::Name</I>' in xsdocparse's data
|
|
structure. Everything from this line to the next <TT>"=cut"</TT> is included as a
|
|
description <FONT SIZE="-1">POD.</FONT>
|
|
<DT id="2">=for object Package::Name (Other::Package::Name)<DD>
|
|
|
|
|
|
Generate <FONT SIZE="-1">POD</FONT> in <I>Package::Name</I> but for the package <I>Other::Package::Name</I>.
|
|
This is useful if you want <FONT SIZE="-1">POD</FONT> to appear in a different namespace but still
|
|
want the automatically generated hierarchy, signal and property listing,
|
|
etc. from the original namespace. For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
=for object Gnome2::PanelApplet::main (Gnome2::PanelApplet)
|
|
=cut
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <FONT SIZE="-1">XS</FONT> file.
|
|
<DT id="3">=for enum Package::Name<DD>
|
|
|
|
|
|
|
|
<DT id="4">=for flags Package::Name<DD>
|
|
|
|
|
|
|
|
This causes xsdoc2pod to call <TT>"podify_values"</TT> on <I>Package::Name</I> when
|
|
writing the pod for the current package (as set by an object directive or
|
|
<FONT SIZE="-1">MODULE</FONT> line). Any text in this paragraph, to the next <TT>"=cut"</TT>, is included
|
|
in that section.
|
|
<DT id="5">=for deprecated_by Package::Name<DD>
|
|
|
|
|
|
Used to add a deprecation warning, indicating <I>Package::Name</I> as an
|
|
alternative way to achieve the same functionality. There may be any number
|
|
these in each package.
|
|
<DT id="6">=for see_also some_thing_to_see<DD>
|
|
|
|
|
|
Used to add extra see alsos onto the end of the parents, if any, for a given
|
|
object. Anything following the space behind see_also up to the end of the
|
|
line will be placed onto the list of ``see also''s. There may be any number of
|
|
these in each package.
|
|
<DT id="7">=for apidoc<DD>
|
|
|
|
|
|
|
|
<DT id="8">=for apidoc Full::Symbol::name<DD>
|
|
|
|
|
|
|
|
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 <TT>"=cut"</TT> and
|
|
the xsub).
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Within the apidoc PODs, we recognize a few special directives (the ``for\s+''
|
|
is optional on these):
|
|
<DL COMPACT><DT id="9"><DD>
|
|
<DL COMPACT>
|
|
<DT id="10">=for signature ...<DD>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
=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 */
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="11">=for arg name (type) description<DD>
|
|
|
|
|
|
|
|
<DT id="12">=for arg name description<DD>
|
|
|
|
|
|
|
|
The arg directive adds or overrides an argument description. The
|
|
description text is optional, as is the type specification (the part
|
|
in parentheses). If you want to hide an argument, specify <TT>"__hide__"</TT>
|
|
as its type. The arg name does <I>not</I> need to include a sigil,
|
|
as dollar signs will be added. <FONT SIZE="-1">FIXME</FONT> what about @ for lists?
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="13"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Also, we honor a couple of ``modifiers'' on the =for apidoc line, following the
|
|
symbol name, if present:
|
|
<DL COMPACT>
|
|
<DT id="14">- __hide__<DD>
|
|
|
|
|
|
Do not document this xsub. This is handy in certain situations, e.g., for
|
|
private functions. <FONT SIZE="-1">DESTROY</FONT> always has this turned on, for example.
|
|
<DT id="15">- __gerror__<DD>
|
|
|
|
|
|
This function or method can generate a Glib::Error exception.
|
|
<DT id="16">- __function__<DD>
|
|
|
|
|
|
Generate a function-style signature for this xsub. The default is to
|
|
generate method-style signatures.
|
|
<DT id="17">- __deprecated__<DD>
|
|
|
|
|
|
This function or method is deprecated and should not be used in newly written
|
|
code.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="18"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
(These are actually handled by Glib::ParseXSDoc, but we list them here
|
|
because, well, they're an important part of how you document the <FONT SIZE="-1">XS</FONT> files.)
|
|
</DL>
|
|
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>FUNCTIONS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="19">xsdoc2pod ($datafile, $outdir='blib/lib', index=undef)<DD>
|
|
|
|
|
|
|
|
|
|
Given a <I></I>$datafile<I></I> containing the output of xsdocparse.pl, create in
|
|
<I></I>$outdir<I></I> a pod file for each package, containing everything we can think
|
|
of for that module. Output is controlled by the <TT>"=for object"</TT> directives
|
|
and such in the source code.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="20">add_types (@filenames)<DD>
|
|
|
|
|
|
Parse the given <I></I>@filenames<I></I> for entries to add to the <TT>%basic_types</TT> 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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# a couple of special types
|
|
FooBar Foo::Bar
|
|
Frob localized frobnicator
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
C type decorations such as ``const'' and ``*'' are implied (do not include them),
|
|
and the _ornull variant is handled for you.
|
|
<DT id="21">$string = podify_properties ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Pretty-print the object properties owned by the Glib::Object derivative
|
|
<I></I>$packagename<I></I> and return the text as a string. Returns undef if there
|
|
are no properties or <I></I>$package<I></I> is not a Glib::Object.
|
|
<DT id="22">$string = podify_child_properties ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Pretty-print the child properties owned by the Gtk2::Container derivative
|
|
<I></I>$packagename<I></I> and return the text as a string. Returns undef if there are
|
|
no child properties or <I></I>$package<I></I> is not a Gtk2::Container or similar class
|
|
with a <TT>"list_child_properties()"</TT> method.
|
|
<DT id="23">$string = podify_style_properties ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Pretty-print the style properties owned by the Gtk2::Widget derivative
|
|
<I></I>$packagename<I></I> and return the text as a string. Returns undef if there are
|
|
no style properties or <I></I>$package<I></I> is not a Gtk2::Widget or similar class
|
|
with a <TT>"list_style_properties()"</TT> method.
|
|
<DT id="24">$string = podify_values ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
List and pretty-print the values of the GEnum or GFlags type <I></I>$packagename<I></I>,
|
|
and return the text as a string. Returns undef if <I></I>$packagename<I></I> isn't an
|
|
enum or flags type.
|
|
<DT id="25">$string = podify_signals ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Query, list, and pretty-print the signals associated with <I></I>$packagename<I></I>.
|
|
Returns the text as a string, or undef if there are no signals or
|
|
<I></I>$packagename<I></I> is not a Glib::Object derivative.
|
|
<DT id="26">$string = podify_deprecated_by ($packagename, @deprecated_by)<DD>
|
|
|
|
|
|
|
|
|
|
Creates a deprecation warning for <TT>$packagename</TT>, suggesting using the items
|
|
inside <TT>@deprecated_by</TT> instead.
|
|
<DT id="27">$string = podify_pods ($pods, $position)<DD>
|
|
|
|
|
|
|
|
|
|
Helper function to allow specific placement of generic pod within the auto
|
|
generated pages. Pod sections starting out with =for position <FONT SIZE="-1">XXX,</FONT> where <FONT SIZE="-1">XXX</FONT>
|
|
is one of the following will be placed at a specified position. In the case of
|
|
pod that is to be placed after a particular section that doesn't exist, that
|
|
pod will be still be placed there.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This function is called at all of the specified points through out the process
|
|
of generating pod for a page. Any pod matching the <I>position</I> passed will be
|
|
returned, undef if no matches were found. If <I>position</I> is undef all pods
|
|
without specific position information will be returned. <I>pods</I> is a reference
|
|
to an array of pod hashes.
|
|
<DL COMPACT><DT id="28"><DD>
|
|
<DL COMPACT>
|
|
<DT id="29">•<DD>
|
|
<FONT SIZE="-1">SYNOPSIS</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">NAME</FONT> section
|
|
<DT id="30">•<DD>
|
|
<FONT SIZE="-1">DESCRIPTION</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">SYNOPSIS</FONT> section.
|
|
<DT id="31">•<DD>
|
|
post_hierarchy
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">HIERARCHY</FONT> section.
|
|
<DT id="32">•<DD>
|
|
post_interfaces
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">INTERFACE</FONT> section.
|
|
<DT id="33">•<DD>
|
|
post_methods
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">METHODS</FONT> section.
|
|
<DT id="34">•<DD>
|
|
post_properties
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">PROPERTIES</FONT> section.
|
|
<DT id="35">•<DD>
|
|
post_signals
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">SIGNALS</FONT> section.
|
|
<DT id="36">•<DD>
|
|
post_enums
|
|
|
|
|
|
<P>
|
|
|
|
|
|
After the <FONT SIZE="-1">ENUMS AND FLAGS</FONT> section.
|
|
<DT id="37">•<DD>
|
|
<FONT SIZE="-1">SEE_ALSO</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Replacing the autogenerated <FONT SIZE="-1">SEE ALSO</FONT> section completely.
|
|
<DT id="38">•<DD>
|
|
<FONT SIZE="-1">COPYRIGHT</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Replacing the autogenerated <FONT SIZE="-1">COPYRIGHT</FONT> section completely.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="39"><DD>
|
|
</DL>
|
|
|
|
<DT id="40">$string = podify_ancestors ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Pretty-prints the ancestry of <I></I>$packagename<I></I> 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 <TT>@ISA</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Returns the new text as a string, or undef if <I></I>$packagename<I></I> is not a
|
|
registered GType.
|
|
<DT id="41">$string = podify_interfaces ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Pretty-print the list of GInterfaces that <I></I>$packagename<I></I> implements.
|
|
Returns the text as a string, or undef if the type implements no interfaces.
|
|
<DT id="42">$string = podify_methods ($packagename)<DD>
|
|
|
|
|
|
|
|
|
|
Call <TT>"xsub_to_pod"</TT> on all the xsubs under the key <I></I>$packagename<I></I> in the
|
|
data extracted by xsdocparse.pl.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Returns the new text as a string, or undef if there are no xsubs in
|
|
<I></I>$packagename<I></I>.
|
|
<DT id="43">$string = podify_see_alsos (@entries)<DD>
|
|
|
|
|
|
|
|
|
|
Creates a list of links to be placed in the <FONT SIZE="-1">SEE ALSO</FONT> section of the page.
|
|
Returns undef if nothing is in the input list.
|
|
<DT id="44">$string = get_copyright<DD>
|
|
|
|
|
|
|
|
|
|
Returns a string that will/should be placed on each page. You can control
|
|
the text of this string by calling the class method <I>set_copyright</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If no text has been set, we will attempt to create one for you, using what
|
|
has been passed to <I>set_year</I>, <I>set_authors</I>, and <I>set_main_mod</I>. 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 <FONT SIZE="-1">SEE ALSO</FONT>
|
|
section, and on the assumption that a decent license notice can be found in
|
|
that module's doc, we point the reader there.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <FONT SIZE="-1">LGPL.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
To set them do something similar to the following in the first part of your
|
|
postamble section in Makefile.PL. All occurrences of <br> in the copyright
|
|
are replaced with newlines, to make it easier to put in a multi-line string.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
POD_SET=Glib::GenPod::set_copyright(qq{Copyright 1999 team-foobar<br>LGPL});
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>Glib::MakeHelper::postamble_docs_full()</B> does this sort of thing for you.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Helpers</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="45">$perl_type = convert_type ($ctypestring)<DD>
|
|
|
|
|
|
|
|
|
|
Convert a C type name to a Perl type name.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Uses <TT>%Glib::GenPod::basic_types</TT> 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.
|
|
<DT id="46">$string = xsub_to_pod ($xsub, $sigprefix='')<DD>
|
|
|
|
|
|
|
|
|
|
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).
|
|
<DT id="47">$string = compile_signature ($xsub)<DD>
|
|
|
|
|
|
|
|
|
|
Given an xsub hash, return a string with the call signature for that
|
|
xsub.
|
|
<DT id="48">$string = fixup_arg_name ($name)<DD>
|
|
|
|
|
|
|
|
|
|
Prepend a $ to anything that's not the literal ellipsis string '...'.
|
|
<DT id="49">fixup_default<DD>
|
|
|
|
|
|
Mangle default parameter values from C to Perl values. Mostly, this
|
|
does <FONT SIZE="-1">NULL</FONT> => undef.
|
|
<DT id="50">convert_arg_type<DD>
|
|
|
|
|
|
C type to Perl type conversion for argument types.
|
|
<DT id="51">convert_return_type_to_name<DD>
|
|
|
|
|
|
C type to Perl type conversion suitable for return types.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
Glib::ParseXSDoc
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
|
|
|
|
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.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
Copyright (C) 2003-2004, 2010-2013 by the gtk2-perl team
|
|
<P>
|
|
|
|
This library is free software; you can redistribute it and/or modify
|
|
it under the terms of the Lesser General Public License (<FONT SIZE="-1">LGPL</FONT>). For
|
|
more information, see <A HREF="http://www.fsf.org/licenses/lgpl.txt">http://www.fsf.org/licenses/lgpl.txt</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="52"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="53"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="54"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="55"><A HREF="#lbAE">DOCUMENTING THE XS FILES</A><DD>
|
|
<DT id="56"><A HREF="#lbAF">FUNCTIONS</A><DD>
|
|
<DL>
|
|
<DT id="57"><A HREF="#lbAG">Helpers</A><DD>
|
|
</DL>
|
|
<DT id="58"><A HREF="#lbAH">SEE ALSO</A><DD>
|
|
<DT id="59"><A HREF="#lbAI">AUTHORS</A><DD>
|
|
<DT id="60"><A HREF="#lbAJ">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:44 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|