MDEV-33281 Optimizer hints cleanup: add const specifiers, comments

sql/simple_parser.h

@@ -21,6 +21,41 @@
 
 #include "simple_tokenizer.h"
 
+/*
+  A set of templates for constructing a recursive-descent LL(1) parser.
+
+  One is supposed to define classes corresponding to grammar productions.
+  The class should inherit from the grammar rule template. For example, a
+  grammar rule
+
+    foo := bar, baz
+
+  is implemented with
+
+    class Bar ... ; // "bar" is parsed into Bar object
+    class Baz ... ; // "baz" is parsed into Baz object
+
+    // "foo" is parsed into a Foo object.
+    class Foo: public Parser_templates::AND2<PARSER_Impl, Bar, Baz> {
+      using AND2::AND2;
+      ...
+    };
+
+  Parsing code is generated by inheriting AND2's constructors with "using" like
+  shown above. All grammar rule-based classes should also have
+  - a capability to construct an "empty"(i.e. invalid) object with the default
+    constructor. This will be invoked when parsing fails.
+  - operator bool() which returns true if the object is non-empty (i.e. valid)
+    and false otherwise.
+
+  Parsing is done by constructing parser output from the parser object:
+
+    Foo parsed_output(parser);
+
+  PARSER_Impl here is a class implementing a tokenizer and error condition
+  storage, like Extended_string_tokenizer.
+*/
+
 class Parser_templates
 {
 protected: