[perl-Glib-Object-Introspection] Document Glib::Object::Introspection->invoke

[Torsten SchÃnfeld <tsch src gnome org>]

commit 319c115c34fc4183a8f46b295457f81e6d845ffc
Author: Torsten SchÃnfeld <kaffeetisch gmx de>
Date:   Sat Sep 10 21:41:27 2011 +0200

    Document Glib::Object::Introspection->invoke
    
    Rename it from _invoke to make it less private.

 GObjectIntrospection.xs          |    2 +-
 lib/Glib/Object/Introspection.pm |   31 ++++++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 2 deletions(-)
---
diff --git a/GObjectIntrospection.xs b/GObjectIntrospection.xs
index 814f99c..f1e603f 100644
--- a/GObjectIntrospection.xs
+++ b/GObjectIntrospection.xs
@@ -2633,7 +2633,7 @@ _set_field (class, basename, namespace, field, invocant, new_value)
 	g_base_info_unref (namespace_info);
 
 void
-_invoke (class, basename, namespace, method, ...)
+invoke (class, basename, namespace, method, ...)
 	const gchar *basename
 	const gchar_ornull *namespace
 	const gchar *method
diff --git a/lib/Glib/Object/Introspection.pm b/lib/Glib/Object/Introspection.pm
index b1af5af..df158d1 100644
--- a/lib/Glib/Object/Introspection.pm
+++ b/lib/Glib/Object/Introspection.pm
@@ -62,7 +62,7 @@ sub setup {
       }
       *{$corrected_name} = sub {
         shift if $shift_package_name_for{$corrected_name};
-        __PACKAGE__->_invoke($basename,
+        __PACKAGE__->invoke($basename,
                              $is_namespaced ? $namespace : undef,
                              $name,
                              @_);
@@ -131,6 +131,8 @@ include gtk+, webkit, libsoup and many more.
 
 =head1 DESCRIPTION
 
+=head2 C<< Glib::Object::Introspection->setup >>
+
 To allow Glib::Object::Introspection to create bindings for a library, it must
 have installed a typelib file, for example
 C<$prefix/lib/girepository-1.0/Gtk-3.0.typelib>.  In your code you then simply
@@ -195,6 +197,33 @@ The function names refer to those after name corrections.
 
 =back
 
+=head2 C<< Glib::Object::Introspection->invoke >>
+
+To invoke specific functions manually, you can use the low-level C<<
+Glib::Object::Introspection->invoke >>.
+
+  Glib::Object::Introspection->invoke(
+    $basename, $namespace, $function, @args)
+
+=over
+
+=item * $basename is the basename of a library, like 'Gtk'.
+
+=item * $namespace refers to a namespace inside that library, like 'Window'.  Use
+undef here if you want to call a library-global function.
+
+=item * $function is the name of the function you want to invoke.  It can also
+refer to the name of a constant.
+
+=item * @args are the arguments that should be passed to the function.  For a
+method, this should include the invocant.  For a constructor, this should
+include the package name.
+
+=back
+
+C<< Glib::Object::Introspection->invoke >> returns whatever the function being
+invoked returns.
+
 =head1 SEE ALSO
 
 =over