[gherkin-perl] Add module documentation for public API (#1740)

* [gherkin-perl] Add module documentation for public API

* [gherkin] Update CHANGELOG.md

gherkin/CHANGELOG.md

@@ -11,6 +11,9 @@ This document is formatted according to the principles of [Keep A CHANGELOG](htt
 
 ### Added
 
+* [Perl] Documentation for most of the modules
+  ([#1740](https://github.com/cucumber/common/pull/1740) [ehuelsmann])
+
 ### Changed
 
 * [Perl] Changed API to pass around `Cucumber::Messages` instead of hashes

gherkin/perl/lib/Gherkin.pm

@@ -215,6 +215,17 @@ UTF-8 encoded L<NDJSON|http://ndjson.org/> output.
 C<$id_gen> and C<$sink> are as documented in C<from_paths>.
 
 
+=head1 SEE ALSO
+
+=over 8
+
+=item * L<Cucumber::Messages>
+
+=item * L<Gherkin::Parser>
+
+=back
+
+
 =head1 LICENSE
 
 Please see the included LICENSE.txt for the canonical version. In summary:

gherkin/perl/lib/Gherkin/Dialect.pm

@@ -53,3 +53,123 @@ sub ScenarioOutline {
 }
 
 1;
+
+
+__END__
+
+=head1 NAME
+
+Gherkin::Dialect - Dictionary holding keyword translations
+
+=head1 SYNOPSIS
+
+  use Gherkin::Dialect;
+
+  my $dialect = Gherkin::Dialect->new( { dialect => 'em' } );
+
+  # Print the names of the steps in the current dialect:
+  for my $keyword (qw/ Given When Then /) {
+    print "Translations for $keyword:\n";
+    for my $translation (@{ $dialect->$keyword }) {
+      print " - $translation\n";
+    }
+  }
+
+=head1 DESCRIPTION
+
+Dialects represent translations of the keywords in the Gherkin language. This
+module implements a class to manage a set of these dialects and select the
+one to be used for keyword translation lookup. Out of the box, Gherkin comes
+with actual translations, such as C<Afrikaans> as well as 'slang-like'
+translations such as "Pirate English".
+
+This module is used by the L<token matcher|Gherkin::TokenMatcher> to identify
+the type of token (input line) passed to the scanner.
+
+=head1 METHODS
+
+=head2 new( $options )
+
+Constructor.
+
+C<$options> is a hashref with some of the following keys:
+
+=over
+
+=item * dialect
+
+The name of the dialect to use for translation lookup. Defaults to 'en'.
+
+=item * dictionary
+
+A hash of hashes, with the names of the dialects as the keys of the
+primary hash and the names of the Gherkin keywords as the keys of the
+secondary hashes (with the values of the secondary hashes being arrayrefs
+holding the actual translations of the keyword).
+
+Mutually exclusive with C<dictionary_location>.
+
+=item * dictionary_location
+
+Pathname to a JSON file which deserializes into the structure mentioned
+for the C<dictionary> option.
+
+Mutually exclusive with C<dictionary_location>.
+
+=back
+
+In case neither C<dictionary> nor C<dictionary_location> is specified, the
+default dictionary from the L<Cucumber project|https://github.com/cucumber>
+is loaded.
+
+
+=head2 change_dialect( $new_dialect )
+
+Selects a dialect for translation lookup from the current dictionary.
+
+
+=head1 TRANSLATION LOOKUP FUNCTIONS
+
+
+=over
+
+=item * Feature
+
+=item * Rule
+
+=item * Scenario
+
+=item * Background
+
+=item * Examples
+
+=item * Given
+
+=item * When
+
+=item * Then
+
+=item * And
+
+=item * But
+
+=item * ScenarioOutline
+
+=back
+
+
+=head2 SEE ALSO
+
+=over 8
+
+=item * L<Gherkin>
+
+=item * L<Gherkin::TokenMatcher>
+
+=back
+
+=head1 LICENSE
+
+See L<Gherkin>
+
+=cut

gherkin/perl/lib/Gherkin/Parser.pm

@@ -6,3 +6,86 @@ use warnings;
 use base 'Gherkin::Generated::Parser';
 
 1;
+
+
+__END__
+
+=head1 NAME
+
+Gherkin::Parser - Gherkin feature file parser
+
+=head1 SYNOPSIS
+
+  use Gherkin::Parser;
+
+  open my $fh, '<:encoding(UTF-8)', 'my.feature'
+    or die "Error opening 'my.feature': $!;
+  my $content = do { local $/ = undef; <$fh> }; # slurp file content
+  close $fh or warn "Error closing 'my.feature': $!";
+
+  my $parser = Gherkin::Parser->new();
+  my $document_envelope = $parser->parse( \$content );
+
+
+=head1 DESCRIPTION
+
+This module implements a Gherkin feature file parser for Perl based on the canonical
+Gherkin grammar, building an AST (abstract syntax tree) from the provided input.
+
+=head1 METHODS
+
+=head2 new( [$ast_builder], [$token_matcher] )
+
+Constructor. Returns a new C<Gherkin::Parser> instance. When the AST builder instance
+is not provided, one with default settings will be created. The same applies to the
+token matcher.
+
+=head2 parse( $token_scanner, [$uri] )
+
+Parses the content provided through the <$token_scanner>. Returns an
+L<Envelope message|Cucumber::Messages/Cucumber::Messages::Envelope> wrapping a
+L<GherkinDocument message|Cucumber::Messages/Cucumber::Messages::GherkinDocument>.
+
+The value provided for the token scanner can be one of three cases:
+
+=over
+
+=item A reference to a L<Gherkin::TokenScanner> instance
+
+=item A reference to a scalar
+
+In this case, the parameter is assumed to reference the content to be parsed.
+
+=item A scalar value
+
+In this case, the parameter is assumed to be a filename. The file will
+be opened for input and parsed as a feature file.
+
+=back
+
+The C<$uri> parameter is expected to be passed in all but the third case.
+
+=head1 SEE ALSO
+
+=over 8
+
+=item * L<Gherkin>
+
+=item * L<Gherkin::AstBuilder>
+
+=item * L<Gherkin::Dialect>
+
+=item * L<Gherkin::TokenMatcher>
+
+=item * L<Gherkin::TokenScanner>
+
+=item * L<Cucumber::Messages::GherkinDocument|Cucumber::Messages/Cucumber::Messages::GherkinDocument>
+
+=back
+
+
+=head1 LICENSE
+
+See L<Gherkin>.
+
+=cut

gherkin/perl/lib/Gherkin/Pickles/Compiler.pm

@@ -228,3 +228,69 @@ sub _pickle_tag {
 }
 
 1;
+
+__END__
+
+=head1 NAME
+
+Gherkin::Pickles::Compiler - Transform Gherkin to execution plans
+
+=head1 SYNOPSIS
+
+  use Data::Dumper;
+  use Gherkin::Parser;
+  use Gherkin::Pickles::Compiler;
+
+
+  my $parser = Gherkin::Parser->new();
+  my $envelope = $parser->parse( 'my.feature' );
+
+  my $c = 0;
+  Gherkin::Pickles::Compiler->compile( $envelope,
+                                       sub { $c++ },
+                                       sub { print Dumper($_[0]) . "\n" },
+  );
+
+=head1 DESCRIPTION
+
+The pickle compiler translates the Gherkin document representation (AST)
+as represented by a L<Cucumber::Messages::GherkinDocument|Cucumber::Messages/Cucumber::Messages::GherkinDocument>
+message into a series of test execution plans (pickles).
+
+=head1 CLASS METHODS
+
+=head2 compile($envelope, $id_generator, [$sink])
+
+Traverses the gherkin document as wrapped by the C<$envelope> message,
+generating execution plans represented by L<Cucumber::Messages::Pickle
+messages|Cucumber::Messages/Cucumber::Messages::Pickle>.
+
+If a C<$sink> is provided, this function is called for each Pickle being
+generated, with one argument: an envelope messages wrapping a Pickle.
+
+In case no C<$sink> is provided, the pickle messages will be collected and
+returned (each wrapped in an envelope) from the function.
+
+The C<$id_generator> is a generator function responsible for returning unique
+string values, used to identify nodes in the returned Pickles.
+
+=head1 SEE ALSO
+
+=over 8
+
+=item * L<Gherkin>
+
+=item * L<Gherkin::Parser>
+
+=item * L<Cucumber::Messages::Pickle|Cucumber::Messages/Cucumber::Messages::Pickle>
+
+=item * L<Cucumber::Messages::GherkinDocument|Cucumber::Messages/Cucumber::Messages::GherkinDocument>
+
+=back
+
+
+=head1 LICENSE
+
+See L<Gherkin>.
+
+=cut

gherkin/perl/lib/Gherkin/TokenMatcher.pm

@@ -227,3 +227,79 @@ sub match_TableRow {
 }
 
 1;
+
+
+__END__
+
+
+=head1 NAME
+
+Gherkin::TokenMatcher - Line token matching for the Gherkin parser
+
+=head1 SYNOPSIS
+
+  use Gherkin::TokenMatcher;
+  use Gherkin::Dialect;
+
+  # Instantiate a token matcher with the default language 'Emoji'
+  my $matcher = Gherkin::TokenMatcher->new( {
+        dialect => Gherkin::Dialect->new( { dialect => 'em'} )
+  } );
+
+=head1 DESCRIPTION
+
+The Gherkin language has a line-based structure. The parser knows about state,
+but defers identifying the type of line tokens to the token matcher. The
+matcher knows how to identify line tokens based on the grammar's keywords.
+Although the matcher knows how to identify line tokens based on the keywords,
+it depends on L<Gherkin::Dialect> to provide the actual keyword texts.
+
+=head1 METHODS
+
+=head2 new( [$options] )
+
+Constructor.
+
+C<$options> is a hashref with the following keys:
+
+=over
+
+=item C<dialect>
+
+An instance of L<Gherkin::Dialect> to provide the keyword texts used to identify
+the type of line-token being matched.
+
+=back
+
+=head2 dialect_name
+
+Returns the name of the current dialect selected from the C<dialect> instance.
+
+=head2 change_dialect
+
+Changes the selected dialect on the C<dialect> instance. Dialects are groups of
+keywords belonging together; this is how keyword translations are being handled.
+
+=head2 reset
+
+Changes the token scanner's state back to its initial state; used to restart
+scanning a document. Multiple documents may be parsed using a single token
+scanner with a C<reset> call in-between.
+
+=head1 SEE ALSO
+
+=over 8
+
+=item * L<Gherkin>
+
+=item * L<Gherkin::Dialect>
+
+=item * L<Gherkin::Parser>
+
+=back
+
+=head1 LICENSE
+
+See L<Gherkin>.
+
+=cut