Document the invariants on iterators arguments to transform and merge.

In many, but not all, cases they are comparable.  However they should
always be dereferenceable.

Author: martin

src/analyses/ai.h

@@ -48,6 +48,15 @@ class ai_domain_baset
   // b) there is an edge from the last instruction (END_FUNCTION)
   //    of the function to the instruction _following_ the call site
   //    (this also needs to set the LHS, if applicable)
+  //
+  // "this" is the domain before the instruction "from"
+  // "from" is the instruction to be interpretted
+  // "to" is the next instruction (for GOTO, FUNCTION_CALL, END_FUNCTION)
+  //
+  // PRECONDITION(from.is_dereferenceable(), "Must not be _::end()")
+  // PRECONDITION(to.is_dereferenceable(), "Must not be _::end()")
+  // PRECONDITION(are_comparable(from,to) ||
+  //              (from->is_function_call() || from->is_end_function())
 
   virtual void transform(
     locationt from,
@@ -90,6 +99,11 @@ class ai_domain_baset
   //
   // This computes the join between "this" and "b".
   // Return true if "this" has changed.
+  // In the usual case, "b" is the updated state after "from"
+  // and "this" is the state before "to".
+  //
+  // PRECONDITION(from.is_dereferenceable(), "Must not be _::end()")
+  // PRECONDITION(to.is_dereferenceable(), "Must not be _::end()")
 
   // This method allows an expression to be simplified / evaluated using the
   // current state.  It is used to evaluate assertions and in program