TreeExplorer: add warning due to the moving builder operations

this was a design decision, but now I myself run into that obvious mistake;
thus not sure if this is a good design, or if we need a dedicated operation
to finish the builder and retrieve the iterable result.

src/lib/iter-tree-explorer.hpp

@@ -766,7 +766,14 @@ namespace lib {
    * from the actual processing and thus to define tree structured computations
    * based on a not further disclosed, opaque source data structure.
    * 
-   * @todo WIP -- preliminary draft as of 11/2017
+   * @warning deliberately, the builder functions exposed on TreeExplorer will
+   *          _move_ the old object into the new, augmented iterator. This is
+   *          possibly dangerous, since one might be tempted to invoke such a
+   *          builder function on an existing iterator variable captured by auto.
+   * @todo if this turns out as a problem on the long run, we'll need to block
+   *          the iterator operations on the builder (by inheriting protected)
+   *          and provide an explicit `build()`-function, which removes the
+   *          builder API and unleashes or slices down to the iterator instead.
    */
   template<class SRC>
   class TreeExplorer
@@ -892,6 +899,10 @@ namespace lib {
    * by suitably wrapping the given iterable source.
    * @return a TreeEplorer, which is an Iterator to yield all the source elements,
    *         but may also be used to build an processing pipeline.
+   * @warning if you capture the result of this call by an auto variable,
+   *         be sure to understand that invoking any further builder operation on
+   *         TreeExplorer will invalidate that variable (by moving it into the
+   *         augmented iterator returned from that builder call).
    */
   template<class IT>
   inline auto

tests/library/iter-tree-explorer-test.cpp

@@ -717,8 +717,8 @@ namespace test{
                  // also the first element of the original sequence after the
                  // expanded children
           
-          CHECK (not isnil(kk));
-          CHECK (14 == *kk);
+          // WARNING: kk is now defunct, since we moved it into the builder expression
+          //          and then moved the resulting extended iterator into materialise!
         }