1GenPod(3) User Contributed Perl Documentation 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 Glib::ParseXS‐
39 Doc's "xsdocparse". This function creates an file containing Perl code
40 that may be eval'd or require'd to recreate the parsed data structures,
41 which are a list of pods from the verbatim C portion of the XS file
42 (the xs api docs), and a hash of the remaining data, keyed by package
43 name, and including the pods and xsubs read from the rest of each XS
44 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 MOD‐
52 ULE line will be placed under the key 'Package::Name' in xsdoc‐
53 parse's data structure. Everything from this line to the next
54 "=cut" is included as a description POD.
55 =for enum Package::Name
57 =for flags Package::Name
58 This causes xsdoc2pod to call "podify_values" on Package::Name when
59 writing the pod for the current package (as set by an object direc‐
60 tive or MODULE line). Any text in this paragraph, to the next
61 "=cut", is included in that section.
62 =for see_also some_thing_to_see
64 Used to add extra see alsos onto the end of the parents, if any,
65 for a given object. Anything following the space behind see_also
66 up to the end of the line will be placed onto the list of "see
67 also"s. There may be any number of these in each package.
68 =for apidoc
70 =for apidoc Full::Symbol::name
71 Paragraphs of this type document xsubs, and are associated with the
72 xsubs by xsdocparse.pl. If the full symbol name is not included,
73 the paragraph must be attached to the xsub declaration (no blank
74 lines between "=cut" and the xsub).
75 Within the apidoc PODs, we recognize a few special directives (the
77 "for\s+" is optional on these):
78 =for signature ...
80 Override the generated call signature with the ... text. If
81 you include multiple signature directives, they will all be
82 used. This is handy when you want to change the return type or
83 list different ways to invoke an overloaded method, like this:
84 =for apidoc
86 =signature bool Class->foo
88 =signature ($thing, @other) = $object->foo ($it, $something)
90 Text in here is included in the generated documentation.
92 You can actually include signature and arg directives
93 at any point in this pod -- they are stripped after.
94 In fact, any pod is valid in here, until the =cut.
95 =cut
97 void foo (...)
98 PPCODE:
99 /* crazy code follows */
100 =for arg name (type) description
102 =for arg name description
103 The arg directive adds or overrides an argument description.
104 The description text is optional, as is the type specification
105 (the part in parentheses). The arg name does not need to
106 include a sigil, as dollar signs will be added. FIXME what
107 about @ for lists?
108 Also, we honor a couple of "modifiers" on the =for apidoc line,
110 following the symbol name, if present:
111 - __hide__
113 Do not document this xsub. This is handy in certain situa‐
114 tions, e.g., for private functions. DESTROY always has this
115 turned on, for example.
116 - __gerror__
118 This function or method can generate a Glib::Error exception.
119 - __function__
121 Generate a function-style signature for this xsub. The default
122 is to generate method-style signatures.
123 (These are actually handled by Glib::ParseXSDoc, but we list them
125 here because, well, they're an important part of how you document
126 the XS files.)
127
129 xsdoc2pod ($datafile, $outdir='blib/lib', index=undef)
130 Given a $datafile containing the output of xsdocparse.pl, create in
131 $outdir a pod file for each package, containing everything we can
132 think of for that module. Output is controlled by the "=for
133 object" directives and such in the source code.
134 If you don't want each package to create a separate pod file, then
136 use this function's code as a starting point for your own
137 pretty-printer.
138 add_types (@filenames)
140 Parse the given @filenames for entries to add to the %basic_types
141 used for C type name to Perl package name mappings of types that
142 are not registered with the Glib type system. The file format is
143 dead simple: blank lines are ignored; /#.*$/ is stripped from each
144 line as comments; the first token on each line is considered to be
145 a C type name, and the remaining tokens are the description of that
146 type. For example, a valid file may look like this:
147 # a couple of special types
149 FooBar Foo::Bar
150 Frob localized frobnicator
151 C type decorations such as "const" and "*" are implied (do not
153 include them), and the _ornull variant is handled for you.
154 $string = podify_properties ($packagename)
156 Pretty-print the object properties owned by the Glib::Object deriv‐
157 ative $packagename and return the text as a string. Returns undef
158 if there are no properties or $package is not a Glib::Object.
159 $string = podify_values ($packagename)
161 List and pretty-print the values of the GEnum or GFlags type $pack‐
162 agename, and return the text as a string. Returns undef if $packa‐
163 gename isn't an enum or flags type.
164 $string = podify_signals ($packagename)
166 Query, list, and pretty-print the signals associated with $package‐
167 name. Returns the text as a string, or undef if there are no sig‐
168 nals or $packagename is not a Glib::Object derivative.
169 $string = podify_pods ($pods, $position)
171 Helper function to allow specific placement of generic pod within
172 the auto generated pages. Pod sections starting out with =for posi‐
173 tion XXX, where XXX is one of the following will be placed at a
174 specified position. In the case of pod that is to be placed after a
175 particular section that doesn't exist, that pod will be still be
176 placed there.
177 This function is called at all of the specified points through out
179 the process of generating pod for a page. Any pod matching the
180 position passed will be returned, undef if no matches were found.
181 If position is undef all pods without sepcific postion information
182 will be returned. pods is a reference to an array of pod hashes.
183 * SYNOPSIS
185 After the NAME section
186 * DESCRIPTION
188 After the SYNOPSIS section.
189 * post_hierarchy
191 After the HIERARCHY section.
192 * post_interfaces
194 After the INTERFACE section.
195 * post_methods
197 After the METHODS section.
198 * post_properties
200 After the PROPERTIES section.
201 * post_signals
203 After the SIGNALS section.
204 * post_enums
206 After the ENUMS AND FLAGS section.
207 * SEE_ALSO
209 Replacing the autogenerated SEE ALSO section completely.
210 * COPYRIGHT
212 Replacing the autogenerated COPYRIGHT section completely.
213 $string = podify_ancestors ($packagename)
215 Pretty-prints the ancestry of $packagename from the Glib type sys‐
216 tem's point of view. This uses Glib::Type->list_ancestors; see
217 that function's docs for an explanation of why that's different
218 from looking at @ISA.
219 Returns the new text as a string, or undef if $packagename is not a
221 registered GType.
222 $string = podify_interfaces ($packagename)
224 Pretty-print the list of GInterfaces that $packagename implements.
225 Returns the text as a string, or undef if the type implements no
226 interfaces.
227 $string = podify_methods ($packagename)
229 Call "xsub_to_pod" on all the xsubs under the key $packagename in
230 the data extracted by xsdocparse.pl.
231 Returns the new text as a string, or undef if there are no xsubs in
233 $packagename.
234 $string = podify_see_alsos (@entries)
236 Creates a list of links to be placed in the SEE ALSO section of the
237 page. Returns undef if nothing is in the input list.
238 $string = get_copyright
240 Returns a string that will/should be placed on each page. You can
241 control the text of this string by setting the package variable
242 $COPYRIGHT to whatever you like.
243 If $COPYRIGHT is not set, we will attempt to create one for you,
245 using the values of the variables $YEAR, $AUTHOR, and $MAIN_MOD.
246 $YEAR defaults to the current year, $AUTHORS defaults to 'The
247 Gtk2-Perl Team', and $MAIN_MOD defaults to empty. You want
248 $MAIN_MOD to be set to the main module of your extension for the
249 SEE ALSO section, and on the assumption that a decent license
250 notice can be found in that module's doc, we point the reader
251 there.
252 So, in general, you will want to specify at least one of these, so
254 that you don't credit your work to us under the LGPL.
255 To set $COPYRIGHT, $AUTHORS, and/or $MAIN_MOD do something similar
257 to the following in the first part of your postamble section in
258 Makefile.PL. All of the weird escaping is required because this is
259 going through several levels of variable expansion. All occurences
260 of <br> in $COPYRIGHT are replaced with newlines, to make it easier
261 to put in a multi-line string.
262 POD_SET=\\\$\$Glib::GenPod::COPYRIGHT='Copyright 1999 team-foobar<br>LGPL';
264 Glib::MakeHelper::postamble_docs_full() does this sort of thing for
266 you.
267 Helpers
269 $perl_type = convert_type ($ctypestring)
271 Convert a C type name to a Perl type name.
272 Uses %Glib::GenPod::basic_types to look for some known basic types,
274 and uses Glib::Type->package_from_cname to look up the registered
275 package corresponding to a C type name. If no suitable mapping can
276 be found, this just returns the input string.
277 $string = xsub_to_pod ($xsub, $sigprefix='')
279 Convert an xsub hash into a string of pod describing it. Includes
280 the call signature, argument listing, and description, honoring
281 special switches in the description pod (arg and signature over‐
282 rides).
283 $string = compile_signature ($xsub)
285 Given an xsub hash, return a string with the call signature for
286 that xsub.
287 $string = fixup_arg_name ($name)
289 Prepend a $ to anything that's not the literal ellipsis string
290 '...'.
291 fixup_default
293 Mangle default parameter values from C to Perl values. Mostly,
294 this does NULL => undef.
295 convert_arg_type
297 C type to Perl type conversion for argument types.
298 convert_return_type_to_name
300 C type to Perl type conversion suitable for return types.
301
303 Glib::ParseXSDoc
304
306 muppet bashed out the xsub signature generation in a few hours on a
307 wednesday night when band practice was cancelled at the last minute; he
308 and ross mcfarland hacked this module together via irc and email over
309 the next few days.
310
312 Copyright (C) 2003-2004 by the gtk2-perl team
313 This library is free software; you can redistribute it and/or modify it
315 under the terms of the Lesser General Public License (LGPL). For more
316 information, see http://www.fsf.org/licenses/lgpl.txt
317perl v5.8.8 2007-02-26 GenPod(3)