1Glib::GenPod(3)       User Contributed Perl Documentation      Glib::GenPod(3)
2
3
4

NAME

6       Glib::GenPod - POD generation utilities for Glib-based modules
7

SYNOPSIS

9        use Glib::GenPod;
10
11        # use the defaults:
12        xsdoc2pod ($xsdocparse_output_file, $destination_dir);
13
14        # or take matters into your own hands
15        require $xsdocparse_output_file;
16        foreach my $package (sort keys %$data) {
17            print "=head1 NAME\n\n$package\n\n";
18            print "=head1 METHODS\n\n" . podify_methods ($package) . "\n\n";
19        }
20

DESCRIPTION

22       This module includes several utilities for creating pod for xs-based
23       Perl modules which build on the Glib module's foundations.  The most
24       important bits are the logic to convert the data structures created by
25       xsdocparse.pl to describe xsubs and pods into method docs, with call
26       signatures and argument descriptions, and converting C type names into
27       Perl type names.  The rest of the module is mostly boiler-plate code to
28       format and pretty-print information that may be queried from the Glib
29       type system.
30
31       To make life easy for module maintainers, we also include a do-it-all
32       function, xsdoc2pod(), which does pretty much everything for you.  All
33       of the pieces it uses are publically usable, so you can do whatever you
34       like if you don't like the default output.
35

DOCUMENTING THE XS FILES

37       All of the information used as input to the methods included here comes
38       from the XS files of your project, and is extracted by
39       Glib::ParseXSDoc's "xsdocparse".  This function creates an file
40       containing Perl code that may be eval'd or require'd to recreate the
41       parsed data structures, which are a list of pods from the verbatim C
42       portion of the XS file (the xs api docs), and a hash of the remaining
43       data, keyed by package name, and including the pods and xsubs read from
44       the rest of each XS file following the first MODULE line.
45
46       Several custom POD directives are recognized in the XSubs section.
47       Note that each one is sought as a paragraph starter, and must follow a
48       "=cut" directive.
49
50       =for object Package::Name
51           All xsubs and pod from here until the next object directive or
52           MODULE line will be placed under the key 'Package::Name' in
53           xsdocparse's data structure.  Everything from this line to the next
54           "=cut" is included as a description POD.
55
56       =for object Package::Name (Other::Package::Name)
57           Generate POD in Package::Name but for the package
58           Other::Package::Name.  This is useful if you want POD to appear in
59           a different namespace but still want the automatically generated
60           hierarchy, signal and property listing, etc. from the original
61           namespace.  For example:
62
63             =for object Gnome2::PanelApplet::main (Gnome2::PanelApplet)
64             =cut
65
66           This will create Gnome2/PanelApplet/main.pod containing the
67           automatically generated documentation for Gnome2::PanelApplet
68           (hierarchy, signals, etc.) plus the method listing from the current
69           XS file.
70
71       =for enum Package::Name
72       =for flags Package::Name
73           This causes xsdoc2pod to call "podify_values" on Package::Name when
74           writing the pod for the current package (as set by an object
75           directive or MODULE line).  Any text in this paragraph, to the next
76           "=cut", is included in that section.
77
78       =for deprecated_by Package::Name
79           Used to add a deprecation warning, indicating Package::Name as an
80           alternative way to achieve the same functionality.  There may be
81           any number these in each package.
82
83       =for see_also some_thing_to_see
84           Used to add extra see alsos onto the end of the parents, if any,
85           for a given object.  Anything following the space behind see_also
86           up to the end of the line will be placed onto the list of "see
87           also"s.  There may be any number of these in each package.
88
89       =for apidoc
90       =for apidoc Full::Symbol::name
91           Paragraphs of this type document xsubs, and are associated with the
92           xsubs by xsdocparse.pl.  If the full symbol name is not included,
93           the paragraph must be attached to the xsub declaration (no blank
94           lines between "=cut" and the xsub).
95
96           Within the apidoc PODs, we recognize a few special directives (the
97           "for\s+" is optional on these):
98
99           =for signature ...
100               Override the generated call signature with the ... text.  If
101               you include multiple signature directives, they will all be
102               used.  This is handy when you want to change the return type or
103               list different ways to invoke an overloaded method, like this:
104
105                =for apidoc
106
107                =signature bool Class->foo
108
109                =signature ($thing, @other) = $object->foo ($it, $something)
110
111                Text in here is included in the generated documentation.
112                You can actually include signature and arg directives
113                at any point in this pod -- they are stripped after.
114                In fact, any pod is valid in here, until the =cut.
115
116                =cut
117                void foo (...)
118                    PPCODE:
119                       /* crazy code follows */
120
121           =for arg name (type) description
122           =for arg name description
123               The arg directive adds or overrides an argument description.
124               The description text is optional, as is the type specification
125               (the part in parentheses).  If you want to hide an argument,
126               specify "__hide__" as its type.  The arg name does not need to
127               include a sigil, as dollar signs will be added.  FIXME what
128               about @ for lists?
129
130           Also, we honor a couple of "modifiers" on the =for apidoc line,
131           following the symbol name, if present:
132
133           - __hide__
134               Do not document this xsub.  This is handy in certain
135               situations, e.g., for private functions.  DESTROY always has
136               this turned on, for example.
137
138           - __gerror__
139               This function or method can generate a Glib::Error exception.
140
141           - __function__
142               Generate a function-style signature for this xsub.  The default
143               is to generate method-style signatures.
144
145           - __deprecated__
146               This function or method is deprecated and should not be used in
147               newly written code.
148
149           (These are actually handled by Glib::ParseXSDoc, but we list them
150           here because, well, they're an important part of how you document
151           the XS files.)
152

FUNCTIONS

154       xsdoc2pod ($datafile, $outdir='blib/lib', index=undef)
155           Given a $datafile containing the output of xsdocparse.pl, create in
156           $outdir a pod file for each package, containing everything we can
157           think of for that module.  Output is controlled by the "=for
158           object" directives and such in the source code.
159
160           If you don't want each package to create a separate pod file, then
161           use this function's code as a starting point for your own pretty-
162           printer.
163
164       add_types (@filenames)
165           Parse the given @filenames for entries to add to the %basic_types
166           used for C type name to Perl package name mappings of types that
167           are not registered with the Glib type system.  The file format is
168           dead simple: blank lines are ignored; /#.*$/ is stripped from each
169           line as comments; the first token on each line is considered to be
170           a C type name, and the remaining tokens are the description of that
171           type.  For example, a valid file may look like this:
172
173             # a couple of special types
174             FooBar      Foo::Bar
175             Frob        localized frobnicator
176
177           C type decorations such as "const" and "*" are implied (do not
178           include them), and the _ornull variant is handled for you.
179
180       $string = podify_properties ($packagename)
181           Pretty-print the object properties owned by the Glib::Object
182           derivative $packagename and return the text as a string.  Returns
183           undef if there are no properties or $package is not a Glib::Object.
184
185       $string = podify_child_properties ($packagename)
186           Pretty-print the child properties owned by the Gtk2::Container
187           derivative $packagename and return the text as a string.  Returns
188           undef if there are no child properties or $package is not a
189           Gtk2::Container or similar class with a "list_child_properties()"
190           method.
191
192       $string = podify_style_properties ($packagename)
193           Pretty-print the style properties owned by the Gtk2::Widget
194           derivative $packagename and return the text as a string.  Returns
195           undef if there are no style properties or $package is not a
196           Gtk2::Widget or similar class with a "list_style_properties()"
197           method.
198
199       $string = podify_values ($packagename)
200           List and pretty-print the values of the GEnum or GFlags type
201           $packagename, and return the text as a string.  Returns undef if
202           $packagename isn't an enum or flags type.
203
204       $string = podify_signals ($packagename)
205           Query, list, and pretty-print the signals associated with
206           $packagename.  Returns the text as a string, or undef if there are
207           no signals or $packagename is not a Glib::Object derivative.
208
209       $string = podify_deprecated_by ($packagename, @deprecated_by)
210           Creates a deprecation warning for $packagename, suggesting using
211           the items inside @deprecated_by instead.
212
213       $string = podify_pods ($pods, $position)
214           Helper function to allow specific placement of generic pod within
215           the auto generated pages. Pod sections starting out with =for
216           position XXX, where XXX is one of the following will be placed at a
217           specified position. In the case of pod that is to be placed after a
218           particular section that doesn't exist, that pod will be still be
219           placed there.
220
221           This function is called at all of the specified points through out
222           the process of generating pod for a page. Any pod matching the
223           position passed will be returned, undef if no matches were found.
224           If position is undef all pods without specific position information
225           will be returned. pods is a reference to an array of pod hashes.
226
227           ·   SYNOPSIS
228
229               After the NAME section
230
231           ·   DESCRIPTION
232
233               After the SYNOPSIS section.
234
235           ·   post_hierarchy
236
237               After the HIERARCHY section.
238
239           ·   post_interfaces
240
241               After the INTERFACE section.
242
243           ·   post_methods
244
245               After the METHODS section.
246
247           ·   post_properties
248
249               After the PROPERTIES section.
250
251           ·   post_signals
252
253               After the SIGNALS section.
254
255           ·   post_enums
256
257               After the ENUMS AND FLAGS section.
258
259           ·   SEE_ALSO
260
261               Replacing the autogenerated SEE ALSO section completely.
262
263           ·   COPYRIGHT
264
265               Replacing the autogenerated COPYRIGHT section completely.
266
267       $string = podify_ancestors ($packagename)
268           Pretty-prints the ancestry of $packagename from the Glib type
269           system's point of view.  This uses Glib::Type->list_ancestors; see
270           that function's docs for an explanation of why that's different
271           from looking at @ISA.
272
273           Returns the new text as a string, or undef if $packagename is not a
274           registered GType.
275
276       $string = podify_interfaces ($packagename)
277           Pretty-print the list of GInterfaces that $packagename implements.
278           Returns the text as a string, or undef if the type implements no
279           interfaces.
280
281       $string = podify_methods ($packagename)
282           Call "xsub_to_pod" on all the xsubs under the key $packagename in
283           the data extracted by xsdocparse.pl.
284
285           Returns the new text as a string, or undef if there are no xsubs in
286           $packagename.
287
288       $string = podify_see_alsos (@entries)
289           Creates a list of links to be placed in the SEE ALSO section of the
290           page.  Returns undef if nothing is in the input list.
291
292       $string = get_copyright
293           Returns a string that will/should be placed on each page.  You can
294           control the text of this string by calling the class method
295           set_copyright.
296
297           If no text has been set, we will attempt to create one for you,
298           using what has been passed to set_year, set_authors, and
299           set_main_mod.  The year defaults to the current year, the authors
300           default to 'The Gtk2-Perl Team', and the main mod is empty by
301           default.  You want the main mod to be set to the main module of
302           your extension for the SEE ALSO section, and on the assumption that
303           a decent license notice can be found in that module's doc, we point
304           the reader there.
305
306           So, in general, you will want to specify at least one of these, so
307           that you don't credit your work to us under the LGPL.
308
309           To set them do something similar to the following in the first part
310           of your postamble section in Makefile.PL.  All occurrences of <br>
311           in the copyright are replaced with newlines, to make it easier to
312           put in a multi-line string.
313
314             POD_SET=Glib::GenPod::set_copyright(qq{Copyright 1999 team-foobar<br>LGPL});
315
316           Glib::MakeHelper::postamble_docs_full() does this sort of thing for
317           you.
318
319   Helpers
320       $perl_type = convert_type ($ctypestring)
321           Convert a C type name to a Perl type name.
322
323           Uses %Glib::GenPod::basic_types to look for some known basic types,
324           and uses Glib::Type->package_from_cname to look up the registered
325           package corresponding to a C type name.  If no suitable mapping can
326           be found, this just returns the input string.
327
328       $string = xsub_to_pod ($xsub, $sigprefix='')
329           Convert an xsub hash into a string of pod describing it.  Includes
330           the call signature, argument listing, and description, honoring
331           special switches in the description pod (arg and signature
332           overrides).
333
334       $string = compile_signature ($xsub)
335           Given an xsub hash, return a string with the call signature for
336           that xsub.
337
338       $string = fixup_arg_name ($name)
339           Prepend a $ to anything that's not the literal ellipsis string
340           '...'.
341
342       fixup_default
343           Mangle default parameter values from C to Perl values.  Mostly,
344           this does NULL => undef.
345
346       convert_arg_type
347           C type to Perl type conversion for argument types.
348
349       convert_return_type_to_name
350           C type to Perl type conversion suitable for return types.
351

SEE ALSO

353       Glib::ParseXSDoc
354

AUTHORS

356       muppet bashed out the xsub signature generation in a few hours on a
357       wednesday night when band practice was cancelled at the last minute; he
358       and ross mcfarland hacked this module together via irc and email over
359       the next few days.
360
362       Copyright (C) 2003-2004, 2010-2013 by the gtk2-perl team
363
364       This library is free software; you can redistribute it and/or modify it
365       under the terms of the Lesser General Public License (LGPL).  For more
366       information, see http://www.fsf.org/licenses/lgpl.txt
367
368
369
370perl v5.30.1                      2020-02-18                   Glib::GenPod(3)
Impressum