From 51e87973080d93d6db2d69ac5ffcd4115b1a81d5 Mon Sep 17 00:00:00 2001
From: Anatol Belski <ab@php.net>
Date: Mon, 6 Nov 2017 21:47:37 +0000
Subject: [PATCH] Improve doc on RLexer::push() and RLexer::pushState()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343376 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/parle/parle/rlexer/push.xml      | 10 +++++++++-
 reference/parle/parle/rlexer/pushstate.xml |  2 +-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/reference/parle/parle/rlexer/push.xml b/reference/parle/parle/rlexer/push.xml
index 4d44d6ea49..7cd64c07d2 100644
--- a/reference/parle/parle/rlexer/push.xml
+++ b/reference/parle/parle/rlexer/push.xml
@@ -32,6 +32,8 @@
   <para>
    Push a pattern for lexeme recognition.
   </para>
+  <para>A 'start state' and 'exit state' can be specified by using a suitable signature. 
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -57,7 +59,7 @@
     <term><parameter>state</parameter></term>
     <listitem>
      <para>
-      State name.
+      State name. If '*' is used as start state, then the rule is applied to all lexer states.
      </para>
     </listitem>
    </varlistentry>
@@ -67,6 +69,12 @@
       <para>
        New state name, after the rule was applied.
       </para>
+      <para>
+       If '.' is specified as the exit state, then the lexer state is unchanged when that rule matches. An exit state with '&gt;' before the name means push. Use the signature without id for either continuation or to start matching, when a continuation or recursion is required.
+      </para>
+      <para>
+       If '&lt;' is specified as exit state, it means pop. In that case, the signature containing the id can be used to identify the match. Note that even in the case an id is specified, the rule will finish first when all the previous pushes popped.
+      </para>
      </listitem>
    </varlistentry>
    <!--<varlistentry>
diff --git a/reference/parle/parle/rlexer/pushstate.xml b/reference/parle/parle/rlexer/pushstate.xml
index 0a07d9daaa..36c7140dd6 100644
--- a/reference/parle/parle/rlexer/pushstate.xml
+++ b/reference/parle/parle/rlexer/pushstate.xml
@@ -14,7 +14,7 @@
    <methodparam><type>string</type><parameter>state</parameter></methodparam>
   </methodsynopsis>
   <para>
-   This lexer type can have more than one state machine. This allows you to lex different tokens depending on context, thus allowing simple parsing to take place. To allow this, a 'start state' must be specified additionally at the beginning of the <methodname>Parle\RLexer::push</methodname> call and an 'exit state' at the end. If '*' is used as start state, then the rule is applied to all lexer states. If '.' is specified as the exit state, then the lexer state is unchanged when that rule matches.
+	  This lexer type can have more than one state machine. This allows you to lex different tokens depending on context, thus allowing simple parsing to take place. Once a state pushed, it can be used with a suitable <methodname>Parle\RLexer::push</methodname> signature variant. 
   </para>
  </refsect1>