1Glib::GenPod(3) User Contributed Perl Documentation Glib::GenPod(3)
2
6 Glib::GenPod - POD generation utilities for Glib-based modules
7
9 use Glib::GenPod;
10 # use the defaults:
12 xsdoc2pod ($xsdocparse_output_file, $destination_dir);
13 # 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
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 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
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 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 =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 =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 =for object Gnome2::PanelApplet::main (Gnome2::PanelApplet)
64 =cut
65 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 =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 =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 =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 =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 Within the apidoc PODs, we recognize a few special directives (the
97 "for\s+" is optional on these):
98 =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 =for apidoc
106 =signature bool Class->foo
108 =signature ($thing, @other) = $object->foo ($it, $something)
110 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 =cut
117 void foo (...)
118 PPCODE:
119 /* crazy code follows */
120 =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 Also, we honor a couple of "modifiers" on the =for apidoc line,
131 following the symbol name, if present:
132 - __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 - __gerror__
139 This function or method can generate a Glib::Error exception.
140 - __function__
142 Generate a function-style signature for this xsub. The default
143 is to generate method-style signatures.
144 - __deprecated__
146 This function or method is deprecated and should not be used in
147 newly written code.
148 (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
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 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 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 # a couple of special types
174 FooBar Foo::Bar
175 Frob localized frobnicator
176 C type decorations such as "const" and "*" are implied (do not
178 include them), and the _ornull variant is handled for you.
179 $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 $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 $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 $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 $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 $string = podify_deprecated_by ($packagename, @deprecated_by)
210 Creates a deprecation warning for $packagename, suggesting using
211 the items inside @deprecated_by instead.
212 $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 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 • SYNOPSIS
228 After the NAME section
230 • DESCRIPTION
232 After the SYNOPSIS section.
234 • post_hierarchy
236 After the HIERARCHY section.
238 • post_interfaces
240 After the INTERFACE section.
242 • post_methods
244 After the METHODS section.
246 • post_properties
248 After the PROPERTIES section.
250 • post_signals
252 After the SIGNALS section.
254 • post_enums
256 After the ENUMS AND FLAGS section.
258 • SEE_ALSO
260 Replacing the autogenerated SEE ALSO section completely.
262 • COPYRIGHT
264 Replacing the autogenerated COPYRIGHT section completely.
266 $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 Returns the new text as a string, or undef if $packagename is not a
274 registered GType.
275 $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 $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 Returns the new text as a string, or undef if there are no xsubs in
286 $packagename.
287 $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 $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 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 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 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 POD_SET=Glib::GenPod::set_copyright(qq{Copyright 1999 team-foobar<br>LGPL});
315 Glib::MakeHelper::postamble_docs_full() does this sort of thing for
317 you.
318 Helpers
320 $perl_type = convert_type ($ctypestring)
321 Convert a C type name to a Perl type name.
322 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 $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 $string = compile_signature ($xsub)
335 Given an xsub hash, return a string with the call signature for
336 that xsub.
337 $string = fixup_arg_name ($name)
339 Prepend a $ to anything that's not the literal ellipsis string
340 '...'.
341 fixup_default
343 Mangle default parameter values from C to Perl values. Mostly,
344 this does NULL => undef.
345 convert_arg_type
347 C type to Perl type conversion for argument types.
348 convert_return_type_to_name
350 C type to Perl type conversion suitable for return types.
351
353 Glib::ParseXSDoc
354
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 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
367perl v5.38.0 2023-08-01 Glib::GenPod(3)