Added description to lexer interface

Changes

@@ -177,4 +177,5 @@ Revision history for Perl extension Yapp.
 1.21 Fri Aug 04 2017
     - Typo Fixes, POD Spelling (thanks to Gregor Herrmann)
     - Bug Fix, Missing POD Encoding (thanks to Gregor Herrmann)
-
+1.22 Sat Nov 17 2018
+    - Release to the public of ported code

META.json

@@ -32,6 +32,6 @@
       }
    },
    "release_status" : "stable",
-   "version" : "1.21",
+   "version" : "1.22",
    "x_serialization_backend" : "JSON::PP version 2.27300"
 }

META.yml

@@ -17,5 +17,5 @@ no_index:
   directory:
     - t
     - inc
-version: '1.21'
+version: '1.22'
 x_serialization_backend: 'CPAN::Meta::YAML version 0.018'

lib/Parse/Yapphp.pm

@@ -19,7 +19,7 @@ use vars qw($VERSION @ISA);
 use Parse::Yapphp::Output;
 
 # CORRELATION #py001: $VERSION must be changed in both Parse::Yapphp & Parse::Yapphp::Driver
-our $VERSION = '1.21';
+our $VERSION = '1.22';
 
 1;
 

lib/Parse/Yapphp/Driver.pm

@@ -23,7 +23,7 @@ use strict;
 use vars qw ( $VERSION $COMPATIBLE $FILENAME );
 
 # CORRELATION #py001: $VERSION must be changed in both Parse::Yapphp & Parse::Yapphp::Driver
-$VERSION = '1.21';
+$VERSION = '1.22';
 $COMPATIBLE = '0.07';
 $FILENAME=__FILE__;
 

lib/Parse/Yapphp/LexerInterface.php

@@ -13,12 +13,37 @@
 //------------------------------------------------------------------------------
 /*<<$namespace>>*//**
  * Interface LexerInterface
+ *
+ * A parser requires a lexical scanner (lexer). In order to use the generated
+ * parser, you'll have to pass an object implementing this interface to its
+ * constructor.
+ *
+ * Lexers must keep track of their input and analyze it. Their `lex()` method
+ * is called every time the parser requires a new token.
  */
 interface LexerInterface
 {
     /**
+     * The lexical scanner's `lex` method is invoked any time the parser requires
+     * a new token. Implementations must return an array containing the token's name
+     * and its value. End of input must be signaled by returning an array with an empty
+     * token name and undefined (`null`) token value.
+     *
+     * Examples:
+     *
+     * ```php
+     * // Return token "T_IDENTIFIER" with semantic value "variable"
+     * return ['T_IDENTIFIER', 'variable'];
+     *
+     * // Return a semicolon token
+     * return [';', ';'];
+     *
+     * // Indicate end of input
+     * return ['', null];
+     * ```
+     *
      * @param <<$driverclass>> $parser
-     * @return array
+     * @return array Token/value
      */
     public function lex(/*<<$driverclass>>*/ $parser): array;
 }