Added documentation

lib/Parse/RPM/Spec.pm

@@ -105,49 +105,89 @@ __END__
 
 =head1 NAME
 
-Parse::RPM::Spec - Perl extension for blah blah blah
+Parse::RPM::Spec - Perl extension to parse RPM spec files.
 
 =head1 SYNOPSIS
 
   use Parse::RPM::Spec;
-  blah blah blah
+
+  my $spec = Parse::RPM::Spec->new('some_pacakge.spec');
+
+  print $spec->name;    # some_package
+  print $spec->version; # 0.01 (for example)
 
 =head1 DESCRIPTION
 
-Stub documentation for Parse::RPM::Spec, created by h2xs. It looks like the
-author of the extension was negligent enough to leave the stub
-unedited.
+RPM is the package management system used on Linux distributions based on
+Red Hat Linux. These days that includes Fedora, Red Hat Enterprise Linux,
+Centos, SUSE, Mandriva and many more.
 
-Blah blah blah.
+RPMs are build from the source of a packages along with a spec file. The
+spec file controls how the RPM is built.
+
+This module creates Perl objects which module spec files. Currently it gives
+you simple access to various pieces of information from the spec file.
+
+=head1 CAVEAT
+
+This is still in development. I particular it doesn't currently parse all of
+a spec file. It just does the bits that I currently use. I will be adding
+support for the rest of the file very soon.
+
+=head1 METHODS
+
+=head2 $spec = Parse::RPM::Spec->new('some_package.spec')
+
+Creates a new Parse::EPM::Spec object. Takes one mandatory parameter which
+is the path to the spec file that you are interested in. Throws an exception
+if it doesn't find a valid spec.
+
+=head2 $spec->parse_file('some_package.spec')
+
+Parses the given spec file. This is called as part of the initialisation
+carried out by the C<new> method, so there is generally no need to call it
+yourself.
+
+=head2 $spec->name, $spec->version, $spec->release, $spec->summary, $spec->license, $spec->group, $spec->url, $spec->source, $spec->buildroot, $spec->buildarch, $spec->buildrequires, $spec->requires
+
+Attribute accessors for the spec file object. Each one returns a piece of
+information from the spec file header. The C<buildrequires> and C<requires>
+methods are slightly different. Because these keys can have multiple values,
+they return a reference to an array of values.
 
 =head2 EXPORT
 
-None by default.
+None.
 
+=head1 TO DO
 
+Plenty still to do here. Firstly, and most importantly, parsing the rest
+of the spec file.
 
 =head1 SEE ALSO
 
-Mention other useful documentation such as the documentation of
-related modules or operating system documentation (such as man pages
-in UNIX), or any relevant external documentation such as RFCs or
-standards.
+=over 4
 
-If you have a mailing list set up for your module, mention it here.
+=item *
 
-If you have a web site set up for your module, mention it here.
+Red Hat RPM Guide - L<http://docs.fedoraproject.org/drafts/rpm-guide-en/index.html>
+
+=item *
+
+Maximum RPM - L<http://www.rpm.org/max-rpm/s1-rpm-file-format-rpm-file-format.html>
+
+=back
 
 =head1 AUTHOR
 
-Dave Cross, E<lt>dave@localdomainE<gt>
+Dave Cross, E<lt>dave@mag-sol.com<gt>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2008 by Dave Cross
+Copyright (C) 2008 by Magnum Solutions Ltd.
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.10.0 or,
 at your option, any later version of Perl 5 you may have available.
 
-
 =cut