view release on metacpan or  search on metacpan

local/lib/perl5/x86_64-linux-thread-multi/Glib/GenPod.pm  view on Meta::CPAN

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.

=item =for enum Package::Name

=item =for flags Package::Name

This causes xsdoc2pod to call C<podify_values> on I<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 C<=cut>, is included
in that section.

=item =for deprecated_by Package::Name

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

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

=item =for apidoc

=item =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 C<=cut> and
the xsub).

Within the apidoc PODs, we recognize a few special directives (the "for\s+"
is optional on these):

=over

=item =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 */

=item =for arg name (type) description

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

=back

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

=over

=item - __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.

=item - __gerror__

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

=item - __function__

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

=item - __deprecated__

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

=back

(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.)

=back

=head1 FUNCTIONS

=over

=cut

=item xsdoc2pod ($datafile, $outdir='blib/lib', index=undef)

Given a I<$datafile> containing the output of xsdocparse.pl, create in 
I<$outdir> a pod file for each package, containing everything we can think
of for that module.  Output is controlled by the C<=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.

local/lib/perl5/x86_64-linux-thread-multi/Glib/GenPod.pm  view on Meta::CPAN

	}

	$str
}

=item $string = compile_signature ($xsub)

Given an xsub hash, return a string with the call signature for that
xsub.

=cut

sub compile_signature {
	my $xsub = shift;

	my @args;
	@args = @{ $xsub->{args} } if ($xsub->{args});

	my $call;

	if ($xsub->{function}) {
		$call = $xsub->{symname};
	} else {
		# find the method's short name
		my $method = $xsub->{symname};
		$method =~ s/^(.*):://;

		my $package = $1 || $xsub->{package};

		# methods always eat the first arg as the instance.
		my $instance = shift @args;

		my $obj = defined ($instance->{type})
		        ? '$'.$instance->{name}
			: $package;

		$call = "$obj\-E<gt>$method";
	}

	# compile the arg list string
	my $argstr = join ", ", map {
			fixup_arg_name ($_->{name})
			. (defined $_->{default}
			   ? '='.fixup_default ($_->{default})
			   : '')
		} @args;

	# compile the return list string
	my @outlist = map { $_->{name} } @{ $xsub->{outlist} };
	if (defined $xsub->{return_type}) {
		my @retnames = map { convert_return_type_to_name ($_) }
				@{ $xsub->{return_type} };
		unshift @outlist, @retnames;
	}
	my $retstr = @outlist
	           ? (@outlist > 1
		      ? "(".join (", ", @outlist).")"
		      : $outlist[0]
		     )." = "
		   : (defined $xsub->{codetype} and
		      $xsub->{codetype} eq 'PPCODE'
		      ? 'list = '
		      : ''
		     );
	
	"$retstr$call ".($argstr ? "($argstr)" : "");
}

=item $string = fixup_arg_name ($name)

Prepend a $ to anything that's not the literal ellipsis string '...'.

=cut

sub fixup_arg_name {
	my $name = shift;
	my $sigil = $name eq '...' ? '' : '$';
	return $sigil.$name;
}

=item fixup_default

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

=cut

sub fixup_default {
	my $value = shift;
	return (defined ($value) 
	        ? ($value eq 'NULL' ? 'undef' : $value)
		: '');
}

=item convert_arg_type

C type to Perl type conversion for argument types.

=cut

sub convert_arg_type { convert_type (@_) }


=item convert_return_type_to_name

C type to Perl type conversion suitable for return types.

=cut

sub convert_return_type_to_name {
	my $type = convert_type (@_);
	if ($type =~ s/^.*:://) {
		$type = lc $type;
	}
	return $type;
}

sub mkdir_p {
	my $path = shift;
	my @dirs = File::Spec->splitdir ($path);
	my $p = shift @dirs;