Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Glib::GenPod(3)	      User Contributed Perl Documentation      Glib::GenPod(3)

NAME
       Glib::GenPod - POD generation utilities for Glib-based modules

SYNOPSIS
	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";
	}

DESCRIPTION
       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.

DOCUMENTING THE	XS FILES
       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.

       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.

       =for object Package::Name
	   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.

       =for object Package::Name (Other::Package::Name)
	   Generate POD	in Package::Name but for the package
	   Other::Package::Name.  This is useful if you	want POD to appear in
	   a different namespace but still want	the automatically generated
	   hierarchy, signal and property listing, etc.	from the original
	   namespace.  For example:

	     =for object Gnome2::PanelApplet::main (Gnome2::PanelApplet)
	     =cut

	   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
	   XS file.

       =for enum Package::Name
       =for flags Package::Name
	   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.

       =for deprecated_by Package::Name
	   Used	to add a deprecation warning, indicating Package::Name as an
	   alternative way to achieve the same functionality.  There may be
	   any number these in each package.

       =for see_also some_thing_to_see
	   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.

       =for apidoc
       =for apidoc Full::Symbol::name
	   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):

	   =for	signature ...
	       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 */

	   =for	arg name (type)	description
	   =for	arg name description
	       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 "__hide__" as its type.	The arg	name does not need to
	       include a sigil,	as dollar signs	will be	added.	FIXME what
	       about @ for lists?

	   Also, we honor a couple of "modifiers" on the =for apidoc line,
	   following the symbol	name, if present:

	   - __hide__
	       Do not document this xsub.  This	is handy in certain
	       situations, e.g., for private functions.	 DESTROY always	has
	       this turned on, for example.

	   - __gerror__
	       This function or	method can generate a Glib::Error exception.

	   - __function__
	       Generate	a function-style signature for this xsub.  The default
	       is to generate method-style signatures.

	   - __deprecated__
	       This function or	method is deprecated and should	not be used in
	       newly written code.

	   (These are actually handled by Glib::ParseXSDoc, but	we list	them
	   here	because, well, they're an important part of how	you document
	   the XS files.)

FUNCTIONS
       xsdoc2pod ($datafile, $outdir='blib/lib', index=undef)
	   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.

	   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.

       add_types (@filenames)
	   Parse the given @filenames for entries to add to the	%basic_types
	   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:

	     # a couple	of special types
	     FooBar	 Foo::Bar
	     Frob	 localized frobnicator

	   C type decorations such as "const" and "*" are implied (do not
	   include them), and the _ornull variant is handled for you.

       $string = podify_properties ($packagename)
	   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.

       $string = podify_child_properties ($packagename)
	   Pretty-print	the child properties owned by the Gtk2::Container
	   derivative $packagename and return the text as a string.  Returns
	   undef if there are no child properties or $package is not a
	   Gtk2::Container or similar class with a "list_child_properties()"
	   method.

       $string = podify_style_properties ($packagename)
	   Pretty-print	the style properties owned by the Gtk2::Widget
	   derivative $packagename and return the text as a string.  Returns
	   undef if there are no style properties or $package is not a
	   Gtk2::Widget	or similar class with a	"list_style_properties()"
	   method.

       $string = podify_values ($packagename)
	   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.

       $string = podify_signals	($packagename)
	   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.

       $string = podify_deprecated_by ($packagename, @deprecated_by)
	   Creates a deprecation warning for $packagename, suggesting using
	   the items inside @deprecated_by instead.

       $string = podify_pods ($pods, $position)
	   Helper function to allow specific placement of generic pod within
	   the auto generated pages. Pod sections starting out with =for
	   position XXX, where XXX 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.

	   This	function is called at all of the specified points through out
	   the process of generating pod for a page. Any pod matching the
	   position passed will	be returned, undef if no matches were found.
	   If position is undef	all pods without specific position information
	   will	be returned. pods is a reference to an array of	pod hashes.

	   o   SYNOPSIS

	       After the NAME section

	   o   DESCRIPTION

	       After the SYNOPSIS section.

	   o   post_hierarchy

	       After the HIERARCHY section.

	   o   post_interfaces

	       After the INTERFACE section.

	   o   post_methods

	       After the METHODS section.

	   o   post_properties

	       After the PROPERTIES section.

	   o   post_signals

	       After the SIGNALS section.

	   o   post_enums

	       After the ENUMS AND FLAGS section.

	   o   SEE_ALSO

	       Replacing the autogenerated SEE ALSO section completely.

	   o   COPYRIGHT

	       Replacing the autogenerated COPYRIGHT section completely.

       $string = podify_ancestors ($packagename)
	   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.

       $string = podify_interfaces ($packagename)
	   Pretty-print	the list of GInterfaces	that $packagename implements.
	   Returns the text as a string, or undef if the type implements no
	   interfaces.

       $string = podify_methods	($packagename)
	   Call	"xsub_to_pod" on all the xsubs under the key $packagename in
	   the data extracted by xsdocparse.pl.

	   Returns the new text	as a string, or	undef if there are no xsubs in
	   $packagename.

       $string = podify_see_alsos (@entries)
	   Creates a list of links to be placed	in the SEE ALSO	section	of the
	   page.  Returns undef	if nothing is in the input list.

       $string = get_copyright
	   Returns a string that will/should be	placed on each page.  You can
	   control the text of this string by calling the class	method
	   set_copyright.

	   If no text has been set, we will attempt to create one for you,
	   using what has been passed to set_year, set_authors,	and
	   set_main_mod.  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 SEE ALSO section, and	on the assumption that
	   a decent license notice can be found	in that	module's doc, we point
	   the reader there.

	   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 LGPL.

	   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.

	     POD_SET=Glib::GenPod::set_copyright(qq{Copyright 1999 team-foobar<br>LGPL});

	   Glib::MakeHelper::postamble_docs_full() does	this sort of thing for
	   you.

   Helpers
       $perl_type = convert_type ($ctypestring)
	   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.

       $string = xsub_to_pod ($xsub, $sigprefix='')
	   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).

       $string = compile_signature ($xsub)
	   Given an xsub hash, return a	string with the	call signature for
	   that	xsub.

       $string = fixup_arg_name	($name)
	   Prepend a $ to anything that's not the literal ellipsis string
	   '...'.

       fixup_default
	   Mangle default parameter values from	C to Perl values.  Mostly,
	   this	does NULL => undef.

       convert_arg_type
	   C type to Perl type conversion for argument types.

       convert_return_type_to_name
	   C type to Perl type conversion suitable for return types.

SEE ALSO
       Glib::ParseXSDoc

AUTHORS
       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 AND LICENSE
       Copyright (C) 2003-2004,	2010-2013 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

perl v5.32.1			  2020-06-06		       Glib::GenPod(3)

NAME | SYNOPSIS | DESCRIPTION | DOCUMENTING THE XS FILES | FUNCTIONS | SEE ALSO | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Glib::GenPod&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help