Amended lemon docs [skip appveyor]

Author: sergeyklay

parser/zephir.lemon

@@ -8,19 +8,36 @@
  * the LICENSE file that was distributed with this source code.
  */
 
+// All token codes are small integers with #defines that begin with "XX_"
 %token_prefix XX_
+
+// The type of the data attached to each token is xx_parser_token.
 %token_type {xx_parser_token*}
+
+// Default type for non-terminals is zval.
 %default_type {zval}
+
+// The generated parser function takes a 4th argument as follows:
+%extra_argument {xx_parser_status *status}
+
 %default_destructor {
 	if (&$$) {
 		zval_ptr_dtor(&$$);
 	}
 }
-%extra_argument {xx_parser_status *status}
+
+// The name of the generated procedure that implements the parser
+// is as follows:
 %name xx_
 
+// Define operator precedence early so that this is the first occurrence
+// of the operator tokens in the grammer.  Keeping the operators together
+// causes them to be assigned integer values that are close together,
+// which keeps parser tables smaller.
+//
+// The token values assigned to these symbols is determined by the order
+// in which lemon first sees them.
 %left INTERNAL PUBLIC PROTECTED STATIC PRIVATE SCOPED .
-
 %left COMMA .
 %right REQUIRE .
 %right DOUBLEARROW .
@@ -45,16 +62,18 @@
 %right SBRACKET_OPEN .
 %right ARROW .
 
+// The following text is included near the beginning of the C source
+// code file that implements the parser.
 %include {
 #include "parser.h"
 }
+// end %include
 
+// This code runs whenever there is a syntax error
 %syntax_error {
-
 	zval syntax_error;
 
 	array_init(&syntax_error);
-
 	parser_add_str(&syntax_error, "type", "error");
 
 	if (status->scanner_state->start_length) {
@@ -80,7 +99,7 @@
 	}
 }
 
-program ::= xx_language(Q) . {
+input ::= xx_language(Q) . {
 	status->ret = Q;
 }