This is an automated email from the git hooks/post-receive script.

intrigeri pushed a commit to branch experimental
in repository libnet-dbus-perl.

commit 68184fecf32289b29c6c2077ad6a5154235e8098
Author: Daniel P. Berrange <d...@berrange.com>
Date:   Thu Feb 2 16:58:27 2006 +0000

    Added more documentation & a (temporarily disabled) test case using 
Test::Pod::Coverage
---
 Makefile.PL                                  |  4 +-
 lib/Net/DBus/Binding/Message/Error.pm        | 48 ++++++++++++++++++++-
 lib/Net/DBus/Binding/Message/MethodCall.pm   | 32 +++++++++++++-
 lib/Net/DBus/Binding/Message/MethodReturn.pm | 28 ++++++++++++-
 lib/Net/DBus/Binding/Message/Signal.pm       | 43 ++++++++++++++++++-
 lib/Net/DBus/Callback.pm                     | 62 +++++++++++++++++++++++++++-
 t/10-pod-coverage.t                          |  7 ++++
 7 files changed, 212 insertions(+), 12 deletions(-)

diff --git a/Makefile.PL b/Makefile.PL
index c9137ed..4118a40 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -49,13 +49,13 @@ sub test {
     my $mm_test = $self->SUPER::test(@_);
     
     return '
-TO_TEST_PM = $(TO_INST_PM:lib/%.pm=blib/test/%.pm)
+TO_TEST_PM = $(TO_INST_PM:lib/%.pm=blib/test/%.pm.tstamp)
 
 test :: test-syntax
 
 test-syntax: pure_all $(TO_TEST_PM)
 
-blib/test/%.pm: lib/%.pm
+blib/test/%.pm.tstamp: lib/%.pm
        @echo -n "Checking $<: "
        #@perl -I blib/lib -c $<
        @podchecker $<
diff --git a/lib/Net/DBus/Binding/Message/Error.pm 
b/lib/Net/DBus/Binding/Message/Error.pm
index 3d9ab4b..2030256 100644
--- a/lib/Net/DBus/Binding/Message/Error.pm
+++ b/lib/Net/DBus/Binding/Message/Error.pm
@@ -16,7 +16,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
-# $Id: Error.pm,v 1.5 2006/01/27 15:34:24 dan Exp $
+# $Id: Error.pm,v 1.6 2006/02/02 16:58:27 dan Exp $
 
 =pod
 
@@ -24,6 +24,31 @@
 
 Net::DBus::Binding::Message::Error - a message encoding a method call error
 
+=head1 SYNOPSIS
+
+  use Net::DBus::Binding::Message::Error;
+
+  my $error = Net::DBus::Binding::Message::Error->new(
+      replyto => $method_call,
+      name => "org.example.myobject.FooException",
+      description => "Unable to do Foo when updating bar");
+
+  $connection->send($error);
+
+=head1 DESCRIPTION
+
+This module is part of the low-level DBus binding APIs, and
+should not be used by application code. No guarentees are made
+about APIs under the C<Net::DBus::Binding::> namespace being
+stable across releases.
+
+This module provides a convenience constructor for creating
+a message representing an error condition. 
+
+=head1 METHODS
+
+=over 4
+
 =cut
 
 package Net::DBus::Binding::Message::Error;
@@ -36,6 +61,17 @@ use Carp;
 use Net::DBus;
 use base qw(Net::DBus::Binding::Message);
 
+=item my $error = Net::DBus::Binding::Message::Error->new(
+      replyto => $method_call, name => $name, description => $description);
+
+Creates a new message, representing an error which occurred during
+the handling of the method call object passed in as the C<replyto>
+parameter. The C<name> parameter is the formal name of the error
+condition, while the C<description> is a short piece of text giving
+more specific information on the error.
+
+=cut
+
 sub new {
     my $proto = shift;
     my $class = ref($proto) || $proto;
@@ -57,6 +93,12 @@ sub new {
     return $self;
 }
 
+=item my $name = $error->get_error_name
+
+Returns the formal name of the error, as previously passed in via
+the C<name> parameter in the constructor.
+
+=cut
 
 sub get_error_name {
     my $self = shift;
@@ -66,7 +108,9 @@ sub get_error_name {
 
 1;
 
-=pod
+__END__
+
+=back
 
 =head1 AUTHOR
 
diff --git a/lib/Net/DBus/Binding/Message/MethodCall.pm 
b/lib/Net/DBus/Binding/Message/MethodCall.pm
index 02b7975..c7c6b05 100644
--- a/lib/Net/DBus/Binding/Message/MethodCall.pm
+++ b/lib/Net/DBus/Binding/Message/MethodCall.pm
@@ -16,7 +16,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
-# $Id: MethodCall.pm,v 1.4 2006/01/27 15:34:24 dan Exp $
+# $Id: MethodCall.pm,v 1.5 2006/02/02 16:58:27 dan Exp $
 
 
 =pod
@@ -25,6 +25,20 @@
 
 Net::DBus::Binding::Message::MethodCall - a message encoding a method call
 
+=head1 DESCRIPTION
+
+This module is part of the low-level DBus binding APIs, and
+should not be used by application code. No guarentees are made
+about APIs under the C<Net::DBus::Binding::> namespace being
+stable across releases.
+
+This module provides a convenience constructor for creating
+a message representing a method call. 
+
+=head1 METHODS
+
+=over 4
+
 =cut
 
 
@@ -38,6 +52,18 @@ use Carp;
 use Net::DBus;
 use base qw(Exporter Net::DBus::Binding::Message);
 
+=item my $call = Net::DBus::Binding::Message::MethodCall->new(
+  service_name => $service, object_path => $object, 
+  interface => $interface, method_name => $name);
+
+Create a message representing a call on the object located at
+the path C<object_path> within the client owning the well-known
+name given by C<service_name>. The method to be invoked has
+the name C<method_name> within the interface specified by the
+C<interface> parameter.
+
+=cut
+
 sub new {
     my $proto = shift;
     my $class = ref($proto) || $proto;
@@ -60,7 +86,9 @@ sub new {
 
 1;
 
-=pod
+__END__
+
+=back
 
 =head1 AUTHOR
 
diff --git a/lib/Net/DBus/Binding/Message/MethodReturn.pm 
b/lib/Net/DBus/Binding/Message/MethodReturn.pm
index 0075d75..766cfb9 100644
--- a/lib/Net/DBus/Binding/Message/MethodReturn.pm
+++ b/lib/Net/DBus/Binding/Message/MethodReturn.pm
@@ -16,7 +16,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
-# $Id: MethodReturn.pm,v 1.4 2006/01/27 15:34:24 dan Exp $
+# $Id: MethodReturn.pm,v 1.5 2006/02/02 16:58:27 dan Exp $
 
 =pod
 
@@ -24,6 +24,20 @@
 
 Net::DBus::Binding::Message::MethodReturn - a message encoding a method return
 
+=head1 DESCRIPTION
+
+This module is part of the low-level DBus binding APIs, and
+should not be used by application code. No guarentees are made
+about APIs under the C<Net::DBus::Binding::> namespace being
+stable across releases.
+
+This module provides a convenience constructor for creating
+a message representing an method return.
+
+=head1 METHODS
+
+=over 4
+
 =cut
 
 package Net::DBus::Binding::Message::MethodReturn;
@@ -36,6 +50,14 @@ use Carp;
 use Net::DBus;
 use base qw(Exporter Net::DBus::Binding::Message);
 
+=item my $return = Net::DBus::Binding::Message::MethodReturn->new(
+    call => $method_call);
+
+Create a message representing a reply to the method call passed in
+the C<call> parameter.
+
+=cut
+
 sub new {
     my $proto = shift;
     my $class = ref($proto) || $proto;
@@ -55,7 +77,9 @@ sub new {
 
 1;
 
-=pod
+__END__
+
+=back
 
 =head1 AUTHOR
 
diff --git a/lib/Net/DBus/Binding/Message/Signal.pm 
b/lib/Net/DBus/Binding/Message/Signal.pm
index d93e223..ce3c241 100644
--- a/lib/Net/DBus/Binding/Message/Signal.pm
+++ b/lib/Net/DBus/Binding/Message/Signal.pm
@@ -16,7 +16,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
-# $Id: Signal.pm,v 1.5 2006/01/27 15:34:24 dan Exp $
+# $Id: Signal.pm,v 1.6 2006/02/02 16:58:27 dan Exp $
 
 =pod
 
@@ -24,6 +24,31 @@
 
 Net::DBus::Binding::Message::Signal - a message encoding a signal
 
+=head1 SYNOPSIS
+
+  use Net::DBus::Binding::Message::Signal;
+
+  my $signal = Net::DBus::Binding::Message::Signal->new(
+      object_path => "/org/example/myobject",
+      interface => "org.example.myobject",
+      signal_name => "foo_changed");
+
+  $connection->send($signal);
+
+=head1 DESCRIPTION
+
+This module is part of the low-level DBus binding APIs, and
+should not be used by application code. No guarentees are made
+about APIs under the C<Net::DBus::Binding::> namespace being
+stable across releases.
+
+This module provides a convenience constructor for creating
+a message representing a signal. 
+
+=head1 METHODS
+
+=over 4
+
 =cut
 
 package Net::DBus::Binding::Message::Signal;
@@ -36,6 +61,18 @@ use Carp;
 use Net::DBus;
 use base qw(Net::DBus::Binding::Message);
 
+
+=item my $signal = Net::DBus::Binding::Message::Signal->new(
+      object_path => $path, interface => $interface, signal_name => $name);
+
+Creates a new message, representing a signal [to be] emitted by 
+the object located under the path given by the C<object_path>
+parameter. The name of the signal is given by the C<signal_name>
+parameter, and is scoped to the interface given by the
+C<interface> parameter.
+
+=cut
+
 sub new {
     my $proto = shift;
     my $class = ref($proto) || $proto;
@@ -58,7 +95,9 @@ sub new {
 
 1;
 
-=pod
+__END__
+
+=back
 
 =head1 AUTHOR
 
diff --git a/lib/Net/DBus/Callback.pm b/lib/Net/DBus/Callback.pm
index 92801f3..591e763 100644
--- a/lib/Net/DBus/Callback.pm
+++ b/lib/Net/DBus/Callback.pm
@@ -16,7 +16,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #
-# $Id: Callback.pm,v 1.6 2006/01/27 15:34:23 dan Exp $
+# $Id: Callback.pm,v 1.7 2006/02/02 16:58:26 dan Exp $
 
 =pod
 
@@ -24,6 +24,37 @@
 
 Net::DBus::Callback - a callback for receiving reactor events
 
+=head1 SYNOPSIS
+
+  use Net::DBus::Callback;
+
+  # Assume we have a 'terminal' object and its got a method
+  # to be invoked everytime there is input on its terminal.
+  #
+  # To create a callback to invoke this method one might use
+  my $cb = Net::DBus::Callback->new(object => $terminal,
+                                    method => "handle_stdio");
+
+
+  # Whatever is monitoring the stdio channel, would then
+  # invoke the callback, perhaps passing in a parameter with
+  # some 'interesting' data, such as number of bytes available
+  $cb->invoke($nbytes)
+
+  #... which results in a call to
+  #  $terminal->handle_stdio($nbytes)
+
+=head1 DESCRIPTION
+
+This module provides a simple container for storing details
+about a callback to be invoked at a later date. It is used
+when registering to receive events from the L<Net::DBus::Reactor>
+class
+
+=head1 METHODS
+
+=over 4
+
 =cut
 
 package Net::DBus::Callback;
@@ -33,6 +64,23 @@ use strict;
 use warnings;
 use Carp qw(confess);
 
+=item my $cb = Net::DBus::Callback->new(method => $name, [args => \@args])
+
+Creates a new callback object, for invoking a plain old function. The C<method>
+parameter should be the fully qualified function name to invoke, including the
+package name. The optional C<args> parameter is an array reference of 
parameters
+to be pass to the callback, in addition to those passed into the C<invoke> 
method.
+
+=item my $cb = Net::DBus::Callback->new(object => $object, method => $name, 
[args => \@args])
+
+Creates a new callback object, for invoking a method on an object. The 
C<method>
+parameter should be the name of the method to invoke, while the C<object> 
parameter
+should be a blessed object on which the method will be invoked. The optional 
C<args> 
+parameter is an array reference of parameters to be pass to the callback, in 
addition 
+to those passed into the C<invoke> method.
+
+=cut
+
 sub new {
     my $proto = shift;
     my $class = ref($proto) || $proto;
@@ -48,6 +96,14 @@ sub new {
     return $self;
 }
 
+=item $cb->invoke(@args)
+
+Invokes the callback. The argument list passed to the callback
+is a combination of the arguments supplied in the callback
+constructor, followed by the arguments supplied in the C<invoke>
+method.
+
+=cut
 
 sub invoke {
     my $self = shift;
@@ -66,7 +122,9 @@ sub invoke {
 
 1;
 
-=pod
+__END__
+
+=back
 
 =head1 AUTHOR
 
diff --git a/t/10-pod-coverage.t b/t/10-pod-coverage.t
new file mode 100644
index 0000000..07e86dc
--- /dev/null
+++ b/t/10-pod-coverage.t
@@ -0,0 +1,7 @@
+# -*- perl -*-
+
+use Test::More;
+eval "use Test::Pod::Coverage 1.00";
+plan skip_all => "Test::Pod::Coverage 1.00 required for testing POD coverage" 
if $@;
+plan skip_all => "disabled until coverage is complete";
+#all_pod_coverage_ok();

-- 
Alioth's /usr/local/bin/git-commit-notice on 
/srv/git.debian.org/git/pkg-perl/packages/libnet-dbus-perl.git

_______________________________________________
Pkg-perl-cvs-commits mailing list
Pkg-perl-cvs-commits@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits

Reply via email to