[perl-Glib-Object-Introspection] Add docs

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

commit 847b82570a261016e0d719be3a9fcee819906416
Author: Torsten SchÃnfeld <kaffeetisch gmx de>
Date:   Tue Aug 9 16:53:25 2011 +0200

    Add docs

 README                           |   15 ++++++-
 lib/Glib/Object/Introspection.pm |   84 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 93 insertions(+), 6 deletions(-)
---
diff --git a/README b/README
index 4cb8eb3..5fe46e2 100644
--- a/README
+++ b/README
@@ -1,7 +1,10 @@
 Glib::Object::Introspection
 ===========================
 
-XXX
+Glib::Object::Introspection uses the gobject-introspection and libffi projects
+to dynamically create Perl bindings for a wide variety of libraries.  Examples
+include gtk+, webkit, libsoup and many more.
+
 
 INSTALLATION
 ------------
@@ -17,7 +20,15 @@ To install this module type the following:
 DEPENDENCIES
 ------------
 
-XXX
+Glib::Object::Introspection needs this C library:
+
+  gobject-introspection-1.0 >= 0.10.0
+
+and these Perl modules:
+
+  ExtUtils::Depends   >= 0.300
+  ExtUtils::PkgConfig >= 1.000
+  Glib                >= 1.220
 
 
 BUG REPORTS
diff --git a/lib/Glib/Object/Introspection.pm b/lib/Glib/Object/Introspection.pm
index b51a5cf..4aff850 100644
--- a/lib/Glib/Object/Introspection.pm
+++ b/lib/Glib/Object/Introspection.pm
@@ -92,19 +92,95 @@ Glib::Object::Introspection - Dynamically create Perl language bindings
 
 =head1 SYNOPSIS
 
-  XXX
+  use Glib::Object::Introspection;
+  Glib::Object::Introspection->setup(
+    basename => 'Gtk',
+    version => '3.0',
+    package => 'Gtk3');
+  # now GtkWindow, to mention just one example, is available as
+  # Gtk3::Window, and you can call gtk_window_new as Gtk3::Window->new
 
 =head1 ABSTRACT
 
-XXX
+Glib::Object::Introspection uses the gobject-introspection and libffi projects
+to dynamically create Perl bindings for a wide variety of libraries.  Examples
+include gtk+, webkit, libsoup and many more.
 
 =head1 DESCRIPTION
 
-XXX
+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
+call C<< Glib::Object::Introspection->setup >> to set everything up.  This
+method takes a couple of key-value pairs as arguments.  These three are
+mandatory:
+
+=over
+
+=item basename => $basename
+
+The basename of the library that should be wrapped.  If your typelib is called
+C<Gtk-3.0.typelib>, then the basename is 'Gtk'.
+
+=item version => $version
+
+The particular version of the library that should be wrapped, in string form.
+For C<Gtk-3.0.typelib>, it is '3.0'.
+
+=item package => $package
+
+The name of the Perl package where every class and method of the library should
+be rooted.  If a library with basename 'Gtk' contains an object 'GtkWindow',
+and you pick as the package 'Gtk3', then that object will be available as
+'Gtk3::Window'.
+
+=back
+
+The rest are optional:
+
+=over
+
+=item search_path => $search_path
+
+A path that should be used when looking for typelibs.  If you use typelibs from
+system directories, or if your environment is set up correctly, then this
+should not be necessary.
+
+=item name_corrections => { auto_name => new_name, ... }
+
+A hash ref that is used to rename functions and methods.  Use this if you don't
+like the automatically generated mapping for a function or method.  For
+example, if C<g_file_hash> is automatically represented as
+C<Glib::IO::file_hash> but you want C<Glib::IO::File::hash> then pass
+
+  name_corrections => {
+    'Glib::IO::file_hash' => 'Glib::IO::File::hash'
+  }
+
+=item class_static_methods => [ functions1, ... ]
+
+An array ref of function names that you want to be treated as class-static
+methods.  That is, if you want be able to call
+C<Gtk3::Window::list_toplevels> as C<< Gtk3::Window->list_toplevels >>, then
+pass
+
+  class_static_methods => [
+    'Gtk3::Window::list_toplevels'
+  ]
+
+The function names refer to those after name corrections.
+
+=back
 
 =head1 SEE ALSO
 
-XXX
+=over
+
+=item gobject-introspection: L<http://live.gnome.org/GObjectIntrospection>
+
+=item libffi: L<http://sourceware.org/libffi/>
+
+=back
 
 =head1 AUTHORS