Index: /trunk/DataStore/lib/DataStore.pm
===================================================================
--- /trunk/DataStore/lib/DataStore.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: DataStore.pm,v 1.1 2006-03-16 20:56:41 jhoblitt Exp $
+# $Id: DataStore.pm,v 1.2 2006-03-16 21:44:57 jhoblitt Exp $
 
 package DataStore;
@@ -33,6 +33,7 @@
 
 This is a convenience module so that that don't have to individualy load (C<use
-...;>) all of the common DataStore inteface modules.  Please see the
-POD of the individual modules for usage information.
+...;>) all of the common DataStore inteface modules.  Please see the POD of the
+individual modules for usage information.  If this is your browsing of the
+documentation you may want to start with L<DataStore::Product>.
 
 =head1 USAGE
@@ -46,4 +47,60 @@
 
 None.
+
+=head1 EXAMPLE PROGRAM
+
+    #!/usr/bin/perl
+
+    use strict;
+    use warnings;
+
+    # loads DataStore::*
+    use DataStore;
+
+    my $dsp = DataStore::Product->new(
+        uri => 'http://example.org/productid/',
+        last_fileset => 'foobarbaz',
+    );
+
+    # returns a DataStore::Response object
+    my $response = $dsp->request;
+
+    unless ($response->is_success) {
+        die $response->status;
+    }
+
+    # arrayref of DataStore::FileSet objects
+    my $filesets = $response->data;
+
+    # the query could be a success but still return no filesets
+    unless ($filesets) {
+        warn "no filesets returned";
+        exit(0);
+    }
+
+    # returns a DataStore::Response object
+    my $response2 = @$filesets[0]->request;
+
+    unless ($response2->is_success) {
+        die $response2->status;
+    }
+
+    # arrayref of DataStore::File objects
+    my $files = $response->data;
+
+    # the query could be a success but still return no files (is that legal?)
+    unless (@$files) {
+        warn "no files returned";
+        exit(0);
+    }
+
+    # requires a filename
+    my $response3 = @$files[0]->request( filename => '/dev/null' );
+    unless ($response3->is_success) {
+        warn $response3->status;
+        die;
+    }
+
+    # $response3->data is '/dev/null'
 
 =cut
Index: /trunk/DataStore/lib/DataStore/File.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/File.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/File.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: File.pm,v 1.6 2006-03-16 02:47:09 jhoblitt Exp $
+# $Id: File.pm,v 1.7 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::File;
@@ -52,4 +52,6 @@
 
 =head1 DESCRIPTION
+
+This class I<isa> L<DataStore::Record>
 
 =head1 USAGE
@@ -143,21 +145,21 @@
 =over 4
 
-=item * C<uri>
-
-Basic accessor.
-
-=item * C<fileid>
-
-Basic accessor.
-
-=item * C<bytes>
-
-Basic accessor.
-
-=item * C<md5sum>
-
-Basic accessor.
-
-=item * C<type>
+=item * C<uri()>
+
+Basic accessor.
+
+=item * C<fileid()>
+
+Basic accessor.
+
+=item * C<bytes()>
+
+Basic accessor.
+
+=item * C<md5sum()>
+
+Basic accessor.
+
+=item * C<type()>
 
 Basic accessor.
Index: /trunk/DataStore/lib/DataStore/File/Parser.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/File/Parser.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/File/Parser.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: Parser.pm,v 1.6 2006-02-28 03:02:12 jhoblitt Exp $
+# $Id: Parser.pm,v 1.7 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::File::Parser;
@@ -28,5 +28,5 @@
 =head1 NAME
 
-DataStore::File::Parser - parses the DataStore 'File list' format
+DataStore::File::Parser - parses the DataStore 'File' list format
 
 =head1 SYNOPSIS
@@ -34,7 +34,16 @@
     use DataStore::File::Parser;
 
-    my $parser = DataStore::File::Parser->new;
+    my $parser = DataStore::File::Parser->new(
+        base_uri => 'http://example.org/',
+    );
+
+    my @data = $parser->parse($str);
+        or
+    my $data = $parser->parse($str);
+
 
 =head1 DESCRIPTION
+
+This class parses a DataStore listing of I<File>s into an array of L<DataStore::File> objects.
 
 =head1 USAGE
@@ -55,5 +64,19 @@
 Basic constructor.
 
-Accepts no arguments and returns a L<DataStore::File::Parser> object.
+    my $parser = DataStore::File::Parser->new(
+        base_uri => 'http://example.org/',
+    );
+
+Accepts an optional hash and returns a L<DataStore::FileSet::Parser> object.
+
+=over 4
+
+=item * base_uri
+
+The base of the URI to set in the created L<DataStore::File> objects.
+
+This key is optional and defaults to C<http://example.org/>.
+
+=back
 
 =cut
@@ -87,5 +110,12 @@
 =over 4
 
+=item * C<base_uri()>
+
+Basic accessor.
+
 =item * C<parse()>
+
+Accepts a string and returns a list in list context or an arrayref is scalar
+context.  An empty list or undef is returned if the string contained no rows.
 
 =cut
@@ -98,5 +128,5 @@
         {
             type    => SCALAR,
-            regex   => qr/\S+/, # string with atleast 1 non WS char
+            regex   => qr/\S+/, # string with at least 1 non WS char
         }
     );
@@ -164,7 +194,16 @@
     }
 
-    return @data ? \@data : undef;
+    return unless @data;
+    return wantarary ? @data : \@data;
 }
 
+=back
+
+=head1 SEE ALSO
+
+L<DataStore::File>, L<DataStore::FileSet::Parser>
+
+=cut
+
 1;
 
Index: /trunk/DataStore/lib/DataStore/FileSet.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/FileSet.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/FileSet.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: FileSet.pm,v 1.4 2006-03-16 02:47:09 jhoblitt Exp $
+# $Id: FileSet.pm,v 1.5 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::FileSet;
@@ -49,4 +49,6 @@
 
 =head1 DESCRIPTION
+
+This class I<isa> L<DataStore::Record>
 
 =head1 USAGE
Index: /trunk/DataStore/lib/DataStore/FileSet/Parser.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/FileSet/Parser.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/FileSet/Parser.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: Parser.pm,v 1.7 2006-02-28 03:02:12 jhoblitt Exp $
+# $Id: Parser.pm,v 1.8 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::FileSet::Parser;
@@ -20,5 +20,4 @@
 my $time_field = qr/^ (\d{4})-(\d\d)-(\d\d) T (\d\d):(\d\d):(\d\d) Z $/x;
 my $std_field = qr/^[a-z0-9-_.]+$/;
-#my %known_types = map { $_ => 1 } qw( OBJECT DOMEFLAT SKYFLAT BIAS DARK );
 my %known_types = map { $_ => 1 } qw( object domeflat skyflat bias dark );
 
@@ -29,5 +28,5 @@
 =head1 NAME
 
-DataStore::FileSet::Parser - parses the DataStore 'list' format
+DataStore::FileSet::Parser - parses the DataStore 'FileSet' list format
 
 =head1 SYNOPSIS
@@ -35,7 +34,15 @@
     use DataStore::FileSet::Parser;
 
-    my $parser = DataStore::FileSet::Parser->new;
+    my $parser = DataStore::FileSet::Parser->new(
+        base_uri => 'http://example.org/',
+    );
+
+    my @data = $parser->parse($str);
+        or
+    my $data = $parser->parse($str);
 
 =head1 DESCRIPTION
+
+This class parses a DataStore listing of I<FileSet>s into an array of L<DataStore::FileSet> objects.
 
 =head1 USAGE
@@ -56,5 +63,19 @@
 Basic constructor.
 
-Accepts no arguments and returns a L<DataStore::FileSet::Parser> object.
+    my $parser = DataStore::FileSet::Parser->new(
+        base_uri => 'http://example.org/',
+    );
+
+Accepts an optional hash and returns a L<DataStore::FileSet::Parser> object.
+
+=over 4
+
+=item * base_uri
+
+The base of the URI to set in the created L<DataStore::FileSet> objects.
+
+This key is optional and defaults to C<http://example.org/>.
+
+=back
 
 =cut
@@ -88,5 +109,12 @@
 =over 4
 
+=item * C<base_uri()>
+
+Basic accessor.
+
 =item * C<parse()>
+
+Accepts a string and returns a list in list context or an arrayref is scalar
+context.  An empty list or undef is returned if the string contained no rows.
 
 =cut
@@ -99,5 +127,5 @@
         {
             type    => SCALAR,
-            regex   => qr/\S+/, # string with atleast 1 non WS char
+            regex   => qr/\S+/, # string with at least 1 non WS char
         }
     );
@@ -162,7 +190,14 @@
     }
 
-    return @data ? \@data : undef;
+    return unless @data;
+    return wantarary ? @data : \@data;
 }
 
+=head1 SEE ALSO
+
+L<DataStore::FileSet>, L<DataStore::File:Parser>
+
+=cut
+
 1;
 
Index: /trunk/DataStore/lib/DataStore/Product.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/Product.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/Product.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: Product.pm,v 1.4 2006-03-16 02:47:09 jhoblitt Exp $
+# $Id: Product.pm,v 1.5 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::Product;
@@ -48,4 +48,6 @@
 
 =head1 DESCRIPTION
+
+This class I<isa> L<DataStore::Record>
 
 =head1 USAGE
Index: /trunk/DataStore/lib/DataStore/Record.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/Record.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/Record.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: Record.pm,v 1.4 2006-03-14 22:40:15 jhoblitt Exp $
+# $Id: Record.pm,v 1.5 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::Record;
@@ -86,4 +86,6 @@
 =item * C<request()>
 
+This method must be overloaded in sub-classes.
+
 =cut
 
Index: /trunk/DataStore/lib/DataStore/Response.pm
===================================================================
--- /trunk/DataStore/lib/DataStore/Response.pm	(revision 6602)
+++ /trunk/DataStore/lib/DataStore/Response.pm	(revision 6603)
@@ -1,5 +1,5 @@
 # Copyright (C) 2006  Joshua Hoblitt
 #
-# $Id: Response.pm,v 1.2 2006-03-16 02:47:09 jhoblitt Exp $
+# $Id: Response.pm,v 1.3 2006-03-16 21:44:58 jhoblitt Exp $
 
 package DataStore::Response;
@@ -46,4 +46,7 @@
 
 =head1 DESCRIPTION
+
+This class represent the return state of the C<request()> method in
+L<DataStore::Record> sub-classes.
 
 =head1 USAGE
@@ -142,21 +145,21 @@
 =over 4
 
-=item * C<uri>
+=item * C<uri()>
 
 Basic accessor.
 
-=item * C<code>
+=item * C<code()>
 
 Basic accessor.
 
-=item * C<status_line>
+=item * C<status_line()>
 
 Basic accessor.
 
-=item * C<data>
+=item * C<data()>
 
 Basic accessor.
 
-=item * C<request>
+=item * C<request()>
 
 Basic accessor.