Updates requested in the PR: comments.

Author: marek-trtik

src/taint-slicer/irept_instrument.h

@@ -19,6 +19,13 @@ proces of "irept" hierarchical and shared data structures.
 #include <util/irep.h>
 #include <functional>
 
+/// An instrumenter is any function returning from a passed instance of
+/// 'irept' its instrumented version. If the passed instance does not
+/// match the king of 'irept' to be instrumented, the function must return
+/// the same instance to indicate no instrumentation was performed.
+/// Due to performance reasons it is recomended to write instrumenter
+/// functions looking only into the passed instance (i.e. not into
+/// 'irept' hierarchy below the passed instance).
 typedef std::function<irept(irept)> instrumenter_fnt;
 typedef std::function<irept(irept, irept)> pivot_instrumenter_fnt;
 
@@ -31,6 +38,17 @@ typedef std::function<irept(irept, irept)> pivot_instrumenter_fnt;
  Outputs:
 
  Purpose:
+  The function accepts a hierarchy of 'irept's and for each node in
+  the hierarchy it calls the passed instrumenter. The result of the
+  function is a new 'irept' hierarchy constructed from the original
+  one by traversing it bottom-up and by applying the instrumenter on
+  each visited node. It is possible that in the end the new hierarchy
+  shares some nodes with the original hierarchy. Namely, a node in the
+  new hierarchy is NOT a node of the original hierarchy only if
+  (a) The instrumenter returned for that node a new (different) node,
+  (b) The instrumenter returned for that node the same node, but in the
+      sub-hierarchy under that node there is a node for which the case (a)
+      was applied.
 
 \*******************************************************************/
 irept instrument(const irept irep, const instrumenter_fnt &instrumenter);
@@ -44,6 +62,17 @@ irept instrument(const irept irep, const instrumenter_fnt &instrumenter);
  Outputs:
 
  Purpose:
+  The function builds an instrumented copy of a passed hierarchy of
+  'irept's in the same way as the function 'instrument' above. However,
+  this version allows the user to also specify a 'pivot' hierarchy of
+  'irept's providing more refined instrumentation. For instance, the
+  instrumenter is called only on that topological part of the hierarchy
+  matching the topology of the pivot. Also, the instrumenter called for
+  some node may use the corresponding pivot node to decide how the
+  instrumentation will be performed. For example, imagine two nodes of
+  the exactly the same kind of the instrumenter passed with the different
+  kinds of pivot nodes. The intrumenter may then return nodes of different
+  kinds (according to kinds of pivot nodes).
 
 \*******************************************************************/
 irept instrument_using_pivot(