Updated documentation.

README

@@ -27,7 +27,7 @@ Features
 --------
 
 * Well-structured 3-stage compiler; uses dovecot framework and avoids using
-  lex/yucc. Parser doesn't bail on first error, but tries to find more.
+  lex/yucc. Compiler doesn't bail on first error, but tries to find more.
 * Highly extendable with new sieve capabilities. This keeps the possibility
   of plugins in mind. Should eventually provide the necessary infrastructure for 
   at least all currently known (proposed) extensions.  
@@ -38,8 +38,7 @@ What works:
 * Script code generation works for most core commands. Comparators, match-types 
   and address-part modifiers already work.
 * Interpreter runs and dumps core commands and tests. Comparators, match-types and 
-  address-part modifiers have the desired effect. Match type :matches is not 
-  supported yet. Action commands have no effect. 
+  address-part modifiers have the desired effect. Action commands have no effect. 
  
 Extensions and their implementation status:
 
@@ -83,17 +82,20 @@ VALIDATOR: sieve-validator.c
   context is used by the last compiler stage. 
 
 GENERATOR: sieve-generator.c
-  This compiler stage uses a visitor pattern to wander through the ast
+  This last compiler stage uses a visitor pattern to wander through the ast
   and produces sieve byte code (sieve-binary.c).
 
 The resulting binary can be fed to the interpreter for execution:
 
 INTERPRETER: sieve-interpreter.c 
-  The interpreter executes the byte code.
+  The interpreter executes the byte code and produces a sieve_result object. 
+  This result is no more than just a collection of actions to be performed. 
 
 TODO
 ----
 
+* Produce a fully working interpreter that actually executes actions, currently
+  tests are evaluated and actions just print their occurence.
 * Resolve code duplication introduced for handling address-parts and match-types
   in different command implementations. 
 * Further implement error handling and limit the maximum number of errors. 
@@ -101,8 +103,6 @@ TODO
   support as much as possible. 
 * Use dovecot streams for code dump (debugging), currently the code is riddled 
   with printf()s. 
-* Produce a fully working interpreter that actually executes actions, currently
-  tests are evaluated and actions just print their occurence.
 * Give the binary format some more thought, it is currently quite rough and
   to the point. 
 * Produce a substitute sieve plugin for deliver (currently a stub and not 

src/lib-sieve/sieve-commands.c

@@ -247,6 +247,11 @@ const char *sieve_command_type_name(const struct sieve_command *command) {
 	return "??COMMAND-TYPE??";
 }
 
+/* Use this function with caution. The command commits to exiting the block.
+ * When it for some reason does not, the interpretation will break later on, 
+ * because exiting jumps are not generated when they would otherwise be 
+ * necessary.
+ */
 inline void sieve_command_exit_block_unconditionally
 	(struct sieve_command_context *cmd)
 {