From d18e36708db288422b441671499c9fcdb62b2efc Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Fri, 11 Jan 2013 16:48:28 +0100
Subject: [PATCH] re-read the code

OMG....
---
 src/proc/engine/frame-coord.hpp  |  6 +-----
 src/proc/engine/job-planning.hpp | 34 ++++++++++++++++++++++++++------
 src/proc/engine/job.hpp          | 20 +++++++------------
 src/proc/engine/time-anchor.hpp  |  5 +----
 4 files changed, 37 insertions(+), 28 deletions(-)

diff --git a/src/proc/engine/frame-coord.hpp b/src/proc/engine/frame-coord.hpp
index e90a2bc7b..5e70b42eb 100644
--- a/src/proc/engine/frame-coord.hpp
+++ b/src/proc/engine/frame-coord.hpp
@@ -25,7 +25,6 @@
 #define PROC_ENGINE_FRAME_COORD_H
 
 #include "proc/common.hpp"
-//#include "proc/state.hpp"
 #include "proc/mobject/model-port.hpp"
 #include "lib/time/timevalue.hpp"
 #include "lib/time/timequant.hpp"
@@ -36,12 +35,9 @@ namespace proc {
 namespace engine {
   
   using mobject::ModelPort;
-//using lib::time::TimeSpan;
   using lib::time::Duration;
-//using lib::time::FSecs;
   using lib::time::TimeVar;
-//  
-//  class ExitNode;
+  
   
   /**
    * effective coordinates of a frame to be calculated.
diff --git a/src/proc/engine/job-planning.hpp b/src/proc/engine/job-planning.hpp
index c45bf1389..b4a48b39e 100644
--- a/src/proc/engine/job-planning.hpp
+++ b/src/proc/engine/job-planning.hpp
@@ -57,7 +57,22 @@ namespace engine {
 //class ExitNode;
   
 
-  /** 
+  /**
+   * View on the execution planning for a single calculation step.
+   * When this view-frontend becomes accessible, behind the scenes all
+   * the necessary information has be pulled and collected from the
+   * low-level model and the relevant rendering/playback configuration.
+   * Typically, clients will materialise this planning into a Job (descriptor)
+   * ready to be entered into the scheduler.
+   * 
+   * JobPlanning is indeed a view; the represented planning information is not
+   * persisted (other then in the job to be created). The implementation draws
+   * on a recursive exploration of the corresponding JobTicket, which acts as
+   * a general blueprint for creating jobs within this segment of the timeline.
+   * 
+   * @remarks on the implementation level, JobPlanning is used as "state core"
+   *          for a PlanningState iterator, to visit and plan subsequently all
+   *          the individual operations necessary to render a timeline chunk.
    */ 
   class JobPlanning
     {
@@ -216,6 +231,14 @@ namespace engine {
     
   
   
+  
+  /** this is the core operation to drive planning ahead:
+   *  discover the prerequisites of some operation -- here
+   *  "prerequisites" are those operations to be performed
+   *  within separate Jobs beforehand.
+   * @note this function is intended to be flat-mapped (">>=")
+   *       onto a tree-like monad representing the evaluation process.
+   */
   inline PlanningState
   expandPrerequisites (JobPlanning const& calculationStep)
   {
@@ -225,8 +248,9 @@ namespace engine {
   }
   
   
-
-
+  
+  
+  
   /**
    * Abstraction: a Facility to establish frame coordinates
    * and identify and access the execution plan for this frame.
@@ -357,13 +381,11 @@ namespace engine {
     {
       
     public:
-//    JobPlanningSequence() { }
-      
       JobPlanningSequence(engine::FrameCoord startPoint, FrameLocator& locator)
         : ExpandedPlanningSequence(
             JobPlanningChunkStartPoint(
                 PlanningStepGenerator(startPoint,locator))
-            >>= expandPrerequisites)
+            >>= expandPrerequisites)                    // "flat map" (monad operation)
         { }
       
     };
diff --git a/src/proc/engine/job.hpp b/src/proc/engine/job.hpp
index e9cfddcbd..461fa95c8 100644
--- a/src/proc/engine/job.hpp
+++ b/src/proc/engine/job.hpp
@@ -61,9 +61,8 @@ typedef struct lumiera_jobClosure* LumieraJobClosure;
 
 
 /** 
- * invocation parameter for the individual
- * frame calculation job. Embedded into the job descriptor
- * and passed to #lumiera_job_invoke when triggering
+ * invocation parameter for the individual frame calculation job.
+ * Embedded into the job descriptor and passed to #lumiera_job_invoke when triggering
  */
 struct lumiera_jobParameter_struct
   {
@@ -114,26 +113,21 @@ typedef lumiera_jobDescriptor* LumieraJobDescriptor;
 
 
 
+
+
+
 #ifdef __cplusplus  /* ============== C++ Interface ================= */
 
-//#include "proc/common.hpp"
 #include "lib/error.hpp"
-//#include "proc/state.hpp"
 #include "lib/time/timevalue.hpp"
-//#include "lib/time/timequant.hpp"
 
 
 
 namespace proc {
 namespace engine {
   
-//using lib::time::TimeSpan;
-//using lib::time::Duration;
-//using lib::time::FSecs;
-using lib::time::TimeValue;
-using lib::time::Time;
-//  
-//class ExitNode;
+  using lib::time::TimeValue;
+  using lib::time::Time;
   
   typedef lumiera_jobParameter const& JobParameter;
   
diff --git a/src/proc/engine/time-anchor.hpp b/src/proc/engine/time-anchor.hpp
index 7d2b5cc63..e5a29d322 100644
--- a/src/proc/engine/time-anchor.hpp
+++ b/src/proc/engine/time-anchor.hpp
@@ -25,7 +25,6 @@
 #define PROC_ENGINE_TIME_ANCHOR_H
 
 #include "proc/common.hpp"
-//#include "proc/state.hpp"
 #include "backend/real-clock.hpp"
 #include "lib/time/timevalue.hpp"
 #include "proc/play/timings.hpp"
@@ -38,12 +37,10 @@ namespace proc {
 namespace engine {
   
   using backend::RealClock;
-//  using lib::time::TimeSpan;
   using lib::time::Offset;
-//  using lib::time::FSecs;
   using lib::time::TimeVar;
   using lib::time::Time;
-//  class ExitNode;
+  
   
   /**
    * The process of playback or rendering is a continued series of exploration and evaluation.