[4088] Miscellaneous edits to the developer documentation

src/lib/eval/eval.dox

@@ -15,49 +15,53 @@
 /**
   @page dhcpEval libeval - Expression evaluation and client classification
 
+  @section dhcpEvalIntroduction Introduction
+
   The core of the libeval library is a parser that is able to parse an
   expression (e.g. option[123] == 'APC'). This is currently used for client
   classification, but in the future may be also used for other applications.
-  The external interface to the library is @ref isc::eval::EvalContext class.
+
-  Once instantiated, it offers two major methods:
+  The external interface to the library is the @ref isc::eval::EvalContext
-  @ref isc::eval::EvalContext::parseFile that parses content of the file
+  class.  Once instantiated, it offers two major methods:
-  and @ref isc::eval::EvalContext::parseString, which parses specified string.
+  @ref isc::eval::EvalContext::parseFile whch parses the content of a file
-  Once expression is parsed, it is converted to a collection of tokens
+  and @ref isc::eval::EvalContext::parseString, which parses the specified
-  that are stored in Reverse Polish Notation in EvalContext::expression.
+  string.  Once the expression is parsed, it is converted to a collection of
-
+  tokens that are stored in Reverse Polish Notation in
-  Internally, the parser code is generated by flex and bison. Those two
+  EvalContext::expression.
+
+  Internally, the parser code is generated by flex and bison. These two
   tools convert lexer.ll and parser.yy files into a number of .cc and .hh files.
-  To avoid adding flex and bison as dependencies, the result of the
+  To avoid a build of Kea depending on the presence of flex and bison, the
-  generation is checked into the github repository and is distributed in the
+  result of the generation is checked into the github repository and is
-  tarballs.
+  distributed in the tarballs.
 
   @section dhcpEvalLexer Lexer generation using flex
 
-  Flex is used to generate lexer, a piece of code that converts input
+  Flex is used to generate the lexer, a piece of code that converts input
   data into a series of tokens. It contains a small number of directives,
-  but the majority of the code consists of a definition of tokens. These
+  but the majority of the code consists of the definitions of tokens. These
-  are regular expressions that define various tokens, e.g. strings,
+  definitions are regular expressions that define various tokens, e.g. strings,
   numbers, parentheses, etc. Once the expression is matched, the associated
-  action is executed. In majority of the cases a generator method from
+  action is executed. In the majority of the cases a generator method from
-  @ref isc::eval::EvalParser is called. It returns newly created
+  @ref isc::eval::EvalParser is called, which returns returns a newly created
-  bison tokens. The purpose of the lexer is to generate a stream
+  bison token. The purpose of the lexer is to generate a stream
   of tokens that are consumed by the parser.
 
-  lexer.cc and lexer.hh files must not be edited. In case there is a need
+  lexer.cc and lexer.hh must not be edited. If there is a need
   to introduce changes, lexer.ll must be updated and the .cc and .hh files
   regenerated.
 
   @section dhcpEvalParser Parser generation using bison
 
-  Bison is used to generate parser, a piece of code that consumes a
+  Bison is used to generate the parser, a piece of code that consumes a
-  stream of tokens and attempts to match it against defined grammar.
+  stream of tokens and attempts to match it against a defined grammar.
-  Bison parser is created from the parser.yy file. It contains
+  The bison parser is created from parser.yy. It contains
   a number of directives, but the two most important sections are:
-  a list of tokens (for each token defined here, bison will generate
+  a list of tokens (for each token defined here, bison will generate the
-  make_NAMEOFTOKEN method in @ref isc::eval::EvalParser class) and
+  make_NAMEOFTOKEN method in the @ref isc::eval::EvalParser class) and
-  the grammar. Grammar is a tree like structure with possible loops.
+  the grammar. The Grammar is a tree like structure with possible loops.
 
-  Here's an over simplified version of the grammar:
+  Here is an over-simplified version of the grammar:
 
 @code
 01. %start expression;
@@ -79,22 +83,23 @@
 
 This code determines that the grammar starts from expression (line 1).
 The actual definition of expression (lines 3-5) may either be a
-single token or an expression token equals token. Token is further
+single token or an expression "token == token" (EQUAL has been defined as
+"==" elsewhere). Token is further
 defined in lines 7-15: it may either be a string (lines 8-11) or option
-(lines 12-15). When the actual case is defined, respective C++ action
+(lines 12-15). When the actual case is determined, the respective C++ action
-is executed. For example, TokenString class is instantiated with
+is executed. For example, if the token is a string, the TokenString class is
-appropriate values and put onto the expression vector.
+instantiated with the appropriate value and put onto the expression vector.
 
 @section dhcpEvalMakefile Generating parser files
 
- In general case, we do want to avoid generating parser files, so an
+ In the general case, we want to avoid generating parser files, so an
  average user interested in just compiling Kea would not need flex or
  bison. Therefore the generated files are already included in the
  git repository and will be included in the tarball releases.
 
  However, there will be cases when one of the developers would want
  to tweak the lexer.ll and parser.yy files and then regenerate
- the code. For this purpose, two makefile targets were defined:
+ the code. For this purpose, two makefile targets are defined:
  @code
  make parser
  @endcode
@@ -103,16 +108,16 @@ appropriate values and put onto the expression vector.
  make parser-clean
  @endcode
  will remove the files. Generated files removal was also hooked
- into maintainer-clean target.
+ into the maintainer-clean target.
 
 @section dhcpEvalConfigure Configure options
 
  Since the flex/bison tools are not necessary for a regular compilation,
- there are checks conducted during configure, but lack of flex or
+ checks conducted during configure, but the lack of flex or
  bison tools does not stop the configure process. There is a flag
- \--enable-generate-parser that tells configure script that the
+ (--enable-generate-parser) that tells configure script that the
  parser will be generated. With this flag, the checks for flex/bison
- are mandatory. Any missing or too old flex/bison will cause an
+ are mandatory. If either tool is missing or at too early a version, the
- error.
+ configure process will terminate with an error.
 
-*/
+*/