From 7b3eb8ab44f855bf38291032587867db38e118fe Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Wed, 17 Jul 2013 14:41:53 -0400
Subject: document the generator side of things

---
 lib/Spreadsheet/Template/Generator.pm             | 45 +++++++++++++++++++++++
 lib/Spreadsheet/Template/Generator/Parser.pm      | 26 +++++++++++++
 lib/Spreadsheet/Template/Generator/Parser/XLSX.pm | 13 +++++++
 3 files changed, 84 insertions(+)

diff --git a/lib/Spreadsheet/Template/Generator.pm b/lib/Spreadsheet/Template/Generator.pm
index c751e99..79282d7 100644
--- a/lib/Spreadsheet/Template/Generator.pm
+++ b/lib/Spreadsheet/Template/Generator.pm
@@ -5,18 +5,55 @@ use Moose;
 use Class::Load 'load_class';
 use JSON;
 
+=head1 SYNOPSIS
+
+  use Spreadsheet::Template::Generator;
+
+  my $generator = Spreadsheet::Template::Generator->new;
+  open my $fh, '>:encoding(utf8)', 'out.json';
+  $fh->print($generator->generate($filename));
+
+=head1 DESCRIPTION
+
+This module is used to create new templates from existing spreadsheets. You can
+then modify this output to be suitable to use as input for
+L<Spreadsheet::Template> by, for instance, adding in L<Text::Xslate> directives
+to use your actual data, rather than the hardcoded data in the original
+spreadsheet.
+
+=cut
+
+=attr parser_class
+
+The class to use for parsing the spreadsheet. Defaults to
+L<Spreadsheet::Template::Generator::Parser::XLSX>.
+
+=cut
+
 has parser_class => (
     is      => 'ro',
     isa     => 'Str',
     default => 'Spreadsheet::Template::Generator::Parser::XLSX',
 );
 
+=attr parser_options
+
+Options to pass to the parser constructor. Defaults to an empty hashref.
+
+=cut
+
 has parser_options => (
     is      => 'ro',
     isa     => 'HashRef',
     default => sub { {} },
 );
 
+=attr parser
+
+The L<Spreadsheet::Template::Generator::Parser> instance that will be used.
+
+=cut
+
 has parser => (
     is   => 'ro',
     does => 'Spreadsheet::Template::Generator::Parser',
@@ -31,6 +68,14 @@ has parser => (
     },
 );
 
+=method generate($filename)
+
+Returns a string containing the JSON representation of the data contained in
+the spreadsheet file C<$filename>. This representation is documented in
+L<Spreadsheet::Template>.
+
+=cut
+
 sub generate {
     my $self = shift;
     my ($filename) = @_;
diff --git a/lib/Spreadsheet/Template/Generator/Parser.pm b/lib/Spreadsheet/Template/Generator/Parser.pm
index d1d7735..ec22f9f 100644
--- a/lib/Spreadsheet/Template/Generator/Parser.pm
+++ b/lib/Spreadsheet/Template/Generator/Parser.pm
@@ -4,6 +4,32 @@ use Moose::Role;
 
 requires 'parse';
 
+=head1 SYNOPSIS
+
+  package MyParser;
+  use Moose;
+
+  with 'Spreadsheet::Template::Generator::Parser';
+
+  sub parse {
+      # ...
+  }
+
+=head1 DESCRIPTION
+
+This role should be consumed by any class which will be used as the
+C<parser_class> in a L<Spreadsheet::Template::Generator> instance.
+
+=cut
+
+=method parse($filename) (required)
+
+This method should parse the spreadsheet specified by C<$filename> and return
+the intermediate data structure containing all of the data in that spreadsheet.
+The intermediate data format is documented in L<Spreadsheet::Template>.
+
+=cut
+
 no Moose::Role;
 
 1;
diff --git a/lib/Spreadsheet/Template/Generator/Parser/XLSX.pm b/lib/Spreadsheet/Template/Generator/Parser/XLSX.pm
index 17a6c4c..535f889 100644
--- a/lib/Spreadsheet/Template/Generator/Parser/XLSX.pm
+++ b/lib/Spreadsheet/Template/Generator/Parser/XLSX.pm
@@ -6,6 +6,19 @@ use Spreadsheet::ParseXLSX;
 
 with 'Spreadsheet::Template::Generator::Parser::Excel';
 
+=head1 SYNOPSIS
+
+  my $generator = Spreadsheet::Template::Generator->new(
+      parser_class => 'Spreadsheet::Template::Generator::Parser',
+  );
+
+=head1 DESCRIPTION
+
+This is an implementation of L<Spreadsheet::Template::Generator::Parser> for
+XLSX files. It uses L<Spreadsheet::ParseXLSX> to do the parsing.
+
+=cut
+
 sub _create_workbook {
     my $self = shift;
     my ($filename) = @_;
-- 
cgit v1.2.3-54-g00ecf