clean-up and finalise time::Mutation

src/lib/time/mutation.cpp

@@ -21,21 +21,37 @@
 * *****************************************************/
 
 
+/** @file mutation.cpp 
+ ** A collection of concrete forms of time mutation.
+ ** This compilation unit defines some "mutators" based on explicitly given time values,
+ ** to be applied to time durations, time spans and quantised time values. The intended
+ ** usage is to build these "mutators" inline through use of the corresponding static
+ ** builder functions defined in class Mutation. All the mutators defined here are
+ ** "polymorphic value objects", i.e. they can be treated like simple time values, while
+ ** actually hiding the concrete implementation and just exposing the #Mutation interface.
+ ** 
+ ** @remarks these mutators are for casual use at places where you'd intuitively just want
+ **          set a simple more or less hard wired value. The benefit of this seemingly complicated
+ **          solution is that all the tricky corner cases for grid aligned time values will be
+ **          treated automatically. Incidentally, there is another, quite different use case
+ **          for time mutations, when it comes to receive continuous and ongoing changes to
+ **          a time value (e.g. a cursor). This separate use case is handled by time::Control
+ ** 
+ ** @see time::Control
+ ** @see lib::PolymorphicValue
+ ** @see TimeMutation_test
+ ** @see TimeControl_test
+ **
+ */
+
+
 #include "lib/error.hpp"
 #include "lib/time/timevalue.hpp"
 #include "lib/time/timequant.hpp"
 #include "lib/time/timecode.hpp"
 #include "lib/time/mutation.hpp"
-//#include "lib/time.h"
 #include "lib/util-quant.hpp"
-#include "lib/util.hpp"
 
-//#include <tr1/functional>
-
-//using std::string;
-//using util::unConst;
-//using util::floorwrap;
-using util::isnil;
 
 namespace error = lumiera::error;
 
@@ -52,8 +68,9 @@ namespace time {
   
   
   
+  /* Warning: all the classes defined here must be of size below MUTATION_IMPL_SIZE */ 
   
-  /** 
+  /**
    * concrete time value mutation:
    * impose fixed new start time.
    */
@@ -94,7 +111,7 @@ namespace time {
     };
   
   
-  /** 
+  /**
    * concrete time value mutation:
    * set a new overall duration for an extended timespan.
    */
@@ -135,7 +152,7 @@ namespace time {
     };
   
   
-  /** 
+  /**
    * concrete time value mutation:
    * adjust the given time entity by an offset amount.
    */
@@ -175,7 +192,7 @@ namespace time {
     };
   
   
-  /** 
+  /**
    * concrete time value mutation:
    * make the grid aligned time value explicit,
    * and impose the resulting value to the given
@@ -192,7 +209,7 @@ namespace time {
     };
   
   
-  /** 
+  /**
    * concrete time value mutation:
    * nudge target value by the given number of 'steps',
    * relative to the given grid.
@@ -215,7 +232,7 @@ namespace time {
     };
   
   
-  /** 
+  /**
    * concrete time value mutation:
    * nudge based on a implicit grid, which is
    * either a quantised target value's own grid,
@@ -360,4 +377,4 @@ namespace time {
   
   
 }} // lib::time
-  
+

src/lib/time/mutation.hpp

@@ -46,8 +46,16 @@
  ** between multiple time grids may be happen, possibly resulting in a re-quantisation of
  ** the message into the target object's own time grid.
  ** 
- ** @todo WIP-WIP-WIP
- **
+ ** @note this header is defined such as to be used with or without including the time quantisation
+ **      facility, which is a more heavyweight regarding code size and compilation times. For this
+ **      toggle to work, the header \c timequant.hpp needs to be included \em prior to \c mutation.hpp
+ **      Obviously, you can't define any mutation involving quantised (grid aligned) values without this.
+ ** @warning when defining more fancy kinds of concrete mutations using the technique with
+ **      the EncapsulatedMutation to hide the implementation, then please be sure to understand
+ **      the size limitation for the implementation and maybe adjust MUTATION_IMPL_SIZE accordingly.
+ ** @see TimeMutation_test
+ ** @see TimeControl_test
+ ** 
  */
 
 #ifndef LIB_TIME_MUTATION_H
@@ -59,17 +67,12 @@
 #include "lib/symbol.hpp"
 
 #include <boost/noncopyable.hpp>
-//#include <iostream>
-//#include <boost/operators.hpp>
-//#include <string>
 
 
 namespace lib {
 namespace time {
   
   using lib::Symbol;
-//using std::string;
-//using lib::Literal;
   
   LUMIERA_ERROR_DECLARE (INVALID_MUTATION); ///< Changing a time value in this way was not designated
   
@@ -91,7 +94,8 @@ namespace time {
    * Interface: an opaque change imposed onto some time value.
    * 
    * @see time::TimeSpan#accept(Mutation const&)
-   * @todo WIP-WIP-WIP
+   * @see TimeMutation_test
+   * @see polymorphic-value.hpp
    */
   class Mutation
     {
@@ -123,7 +127,7 @@ namespace time {
   
   
   /* === defining the visitation responses === */
-    
+  
   inline void Duration::accept (Mutation const& muta) { muta.change (*this); }
   inline void TimeSpan::accept (Mutation const& muta) { muta.change (*this); }
   
@@ -180,5 +184,6 @@ namespace time {
 #endif
   
   
+  
 }} // lib::time
 #endif

tests/lib/time/time-mutation-test.cpp

@@ -1,5 +1,5 @@
 /*
-  TimeMutation(Test)  -  explicitly changing time spcifications
+  TimeMutation(Test)  -  explicitly changing time specifications
 
   Copyright (C)         Lumiera.org
     2011,               Hermann Vosseler <Ichthyostega@web.de>
@@ -30,13 +30,10 @@
 #include "lib/util.hpp"
 
 #include <boost/lexical_cast.hpp>
-#include <iostream>
 #include <string>
 
 using boost::lexical_cast;
 using util::isnil;
-using std::cout;
-using std::endl;
 using std::string;