[perl-Glib-IO] Document Glib::IO

[Emmanuele Bassi <ebassi src gnome org>]

commit 1ceafe27b3c5a0c4c9e1f31832467eed8c3fde13
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Jul 13 11:46:27 2017 +0100

    Document Glib::IO
    
    It's been a few years, and even though Glib::IO is pretty threadbare we
    should probably do at least a release, to communicate that Perl
    developers should use it. Maybe we'll even receive patches, this way.

 README         |   20 ++++++---
 lib/Glib/IO.pm |  125 +++++++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 123 insertions(+), 22 deletions(-)
---
diff --git a/README b/README
index 28e0f1c..36acb19 100644
--- a/README
+++ b/README
@@ -1,7 +1,7 @@
 Glib::IO
 ========
 
-XXX
+Perl bindings to the GIO library.
 
 INSTALLATION
 ------------
@@ -17,7 +17,13 @@ To install this module type the following:
 DEPENDENCIES
 ------------
 
-XXX
+Glib::IO requires the following C libraries:
+
+  gio-2.0
+
+and the following Perl modules:
+
+  Glib::Object::Introspection >= 0.014
 
 
 BUG REPORTS
@@ -31,17 +37,17 @@ COPYRIGHT AND LICENSE
 ---------------------
 
 Copyright (C) 2010-2015 Torsten Schönfeld <kaffeetisch gmx de>
+Copyright 2017  Emmanuele Bassi
 
 This library is free software; you can redistribute it and/or modify it under
-the terms of the GNU Library General Public License as published by the Free
+the terms of the GNU Lesser General Public License as published by the Free
 Software Foundation; either version 2.1 of the License, or (at your option) any
 later version.
 
 This library is distributed in the hope that it will be useful, but WITHOUT ANY
 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.  See the GNU Library General Public License for more
+PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 details.
 
-You should have received a copy of the GNU Library General Public License along
-with this library; if not, write to the Free Software Foundation, Inc., 59
-Temple Place - Suite 330, Boston, MA 02111-1307 USA.
+You should have received a copy of the GNU Lesser General Public License along
+with this library; if not, see <http://www.gnu.org/licenses/>.
diff --git a/lib/Glib/IO.pm b/lib/Glib/IO.pm
index 6b7e2cb..92d3dd3 100644
--- a/lib/Glib/IO.pm
+++ b/lib/Glib/IO.pm
@@ -8,28 +8,108 @@ Glib::IO - Perl bindings to the GIO library
 
 =head1 SYNOPSIS
 
-  XXX
+  use Glib;
+  use Glib::IO;
+
+  # Synchronous I/O
+  $cur_dir = Glib::IO::File::new_for_path('.');
+  $enumerator = $cur_dir->enumerate_children('standard::*', [], undef);
+  $file_info = $enumerator->next_file(undef);
+  while ($next_file) {
+      say 'Path: ' + $file_info->get_name();
+  }
+
+  # Asynchronous I/O
+  $loop = Glib::MainLoop->new();
+  $file = Glib::IO::File::new_for_path('/etc/passwd');
+  $file->query_info_async('access::can-read,access::can-write', [], 0, sub {
+      my ($file, $res, $data) = @_;
+      my $info = $file->query_info_finish();
+      say 'Can read:  ' + $info->get_attribute_boolean('access::can-read');
+      say 'Can write: ' + $info->get_attribute_boolean('access::can-write');
+      $loop->quit();
+  }
+  $loop->run();
+
+  # Platform API
+  $network_monitor = Glib::IO::NetworkMonitor::get_default();
+  say 'Connected: ', $network_monitor->get_network_available() ? 'Yes' : 'No';
 
 =head1 ABSTRACT
 
-XXX
+Perl bindings to the GIO library. This modules allows you to write portable
+code to perform synchronous and asynchronous I/O; implement IPC clients and
+servers using the DBus specification; interact with the operating system and
+platform using various services.
 
 =head1 DESCRIPTION
 
-XXX
+The C<Glib::IO> module allows a Perl developer to access the GIO library, the
+high level I/O and platform library of the GNOME development platform. GIO is
+used for:
 
-=cut
+=over
 
-use strict;
-use warnings;
-use Glib::Object::Introspection;
+=item * local and remote enumeration and access of files
+
+GIO has multiple backends to access local file systems; SMB/CIFS volumes;
+WebDAV resources; compressed archives; local devices and remote web services.
+
+=item * stream based I/O
+
+Including files, memory buffers, and network streams.
+
+=item * low level and high level network operations
+
+Sockets, Internet addresses, datagram-based connections, and TCP connections.
+
+=item * TLS/SSL support for socket connections
+
+=item * DNS resolution and proxy
+
+=item * low level and high level DBus classes
+
+GIO allows the implementation of clients and servers, as well as proxying
+objects over DBus connections.
+
+=back
+
+Additionally, GIO has a collection of high level classes for writing
+applications that integrate with the platform, like:
+
+=over
+
+=item settings
+
+=item network monitoring
+
+=item a base Application class
 
-=head2 Wrapped libraries
+=item extensible data models
 
-XXX
+=item content type matching
+
+=item application information and launch
+
+=back
+
+For more information, please visit the GIO reference manual available on
+L<https://developer.gnome.org/gio/stable>. The Perl API closely matches the
+C one, and eventual deviations will be documented here.
+
+The principles underlying the mapping from C to Perl are explained in the
+documentation of L<Glib::Object::Introspection>, on which C<Glib::IO> is based.
+
+L<Glib::Object::Introspection> also comes with the C<perli11ndoc> program which
+displays the API reference documentation of all installed libraries organized
+in accordance with these principles.
 
 =cut
 
+use strict;
+use warnings;
+use Glib::Object::Introspection;
+
 my $GIO_BASENAME = 'Gio';
 my $GIO_VERSION = '2.0';
 my $GIO_PACKAGE = 'Glib::IO';
@@ -41,18 +121,30 @@ sub import {
     package => $GIO_PACKAGE);
 }
 
-=head2 Customizations and overrides
-
-XXX
-
-=cut
+#=head2 Customizations and overrides
+#
+#=cut
 
 1;
 __END__
 
 =head1 SEE ALSO
 
-XXX
+=over
+
+=item * To discuss Glib::IO and ask questions join gtk-perl-list gnome org at
+L<http://mail.gnome.org/mailman/listinfo/gtk-perl-list>.
+
+=item * Also have a look at the gtk2-perl website and sourceforge project page,
+L<http://gtk2-perl.sourceforge.net>.
+
+=item * L<Glib>
+
+=item * L<Glib::Object::Introspection>
+
+=item * L<Gtk3>
+
+=back
 
 =head1 AUTHORS
 
@@ -60,11 +152,14 @@ XXX
 
 =item Torsten Schönfeld <kaffeetisch gmx de>
 
+=item Emmanuele Bassi <ebassi gnome org>
+
 =back
 
 =head1 COPYRIGHT AND LICENSE
 
 Copyright (C) 2010-2015 by Torsten Schönfeld <kaffeetisch gmx de>
+Copyright 2017  Emmanuele Bassi
 
 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,