From bfccd99623f7050757ef24d5b123f4eadd23e992 Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Wed, 9 Nov 2016 22:22:55 +0100
Subject: [PATCH] Doxygen: fill in missing file level headlines for Proc-Layer
 (Session)

---
 src/proc/mobject/session/abstractmo.cpp       |  2 +-
 src/proc/mobject/session/abstractmo.hpp       |  2 +-
 src/proc/mobject/session/allocation.cpp       |  2 +-
 src/proc/mobject/session/allocation.hpp       |  3 ++-
 src/proc/mobject/session/auto.cpp             |  2 +-
 src/proc/mobject/session/auto.hpp             |  2 +-
 src/proc/mobject/session/binding.cpp          |  4 ++-
 src/proc/mobject/session/binding.hpp          |  4 ++-
 src/proc/mobject/session/bus-mo.cpp           |  4 ++-
 src/proc/mobject/session/bus-mo.hpp           |  7 ++++-
 src/proc/mobject/session/clip.cpp             | 16 ++++++-----
 src/proc/mobject/session/clip.hpp             |  4 ++-
 src/proc/mobject/session/constraint.cpp       |  2 +-
 src/proc/mobject/session/constraint.hpp       |  3 ++-
 src/proc/mobject/session/effect.cpp           |  4 +--
 src/proc/mobject/session/effect.hpp           |  2 +-
 src/proc/mobject/session/element-query.hpp    |  5 +++-
 src/proc/mobject/session/fixedlocation.cpp    |  3 ++-
 src/proc/mobject/session/fixedlocation.hpp    |  8 +++++-
 src/proc/mobject/session/fixture.cpp          |  4 ++-
 src/proc/mobject/session/fixture.hpp          | 16 ++++++++++-
 src/proc/mobject/session/fork.cpp             |  4 ++-
 src/proc/mobject/session/fork.hpp             | 27 ++++++++++++++++++-
 src/proc/mobject/session/generator-mo.cpp     |  3 ++-
 src/proc/mobject/session/generator-mo.hpp     |  5 +++-
 src/proc/mobject/session/label.cpp            |  2 +-
 src/proc/mobject/session/label.hpp            |  9 ++++++-
 src/proc/mobject/session/locatingpin.cpp      |  6 ++++-
 src/proc/mobject/session/meta.cpp             |  5 +++-
 src/proc/mobject/session/meta.hpp             |  4 ++-
 src/proc/mobject/session/mobjectfactory.cpp   |  3 ++-
 src/proc/mobject/session/mobjectfactory.hpp   |  5 +++-
 .../placement-index-query-resolver.cpp        |  3 ++-
 src/proc/mobject/session/plug.cpp             |  2 +-
 src/proc/mobject/session/plug.hpp             |  4 +--
 .../mobject/session/query-focus-stack.hpp     |  8 +++---
 src/proc/mobject/session/query-focus.cpp      |  3 ++-
 src/proc/mobject/session/query-focus.hpp      | 22 +++++++++++++--
 .../session/query/fake-configrules.cpp        | 14 ++++++++--
 src/proc/mobject/session/relativelocation.cpp |  4 ++-
 src/proc/mobject/session/relativelocation.hpp |  3 ++-
 src/proc/mobject/session/root.cpp             |  3 ++-
 src/proc/mobject/session/root.hpp             | 10 ++++++-
 src/proc/mobject/session/scope-locator.hpp    |  6 +++--
 src/proc/mobject/session/scope-path.cpp       |  3 ++-
 src/proc/mobject/session/scope.hpp            |  3 ++-
 src/proc/mobject/session/segment.cpp          |  3 ++-
 src/proc/mobject/session/segment.hpp          |  4 ++-
 src/proc/mobject/session/segmentation.cpp     |  3 ++-
 src/proc/mobject/session/segmentation.hpp     |  9 ++++++-
 .../mobject/session/sess-manager-impl.cpp     |  2 +-
 .../mobject/session/sess-manager-impl.hpp     | 13 ++++++++-
 src/proc/mobject/session/session-impl.cpp     |  4 ++-
 src/proc/mobject/session/session-services.cpp | 17 +++++++++++-
 .../session/specific-contents-query.hpp       |  7 ++++-
 src/proc/mobject/session/wish.cpp             |  2 +-
 src/proc/mobject/session/wish.hpp             |  3 ++-
 57 files changed, 257 insertions(+), 70 deletions(-)

diff --git a/src/proc/mobject/session/abstractmo.cpp b/src/proc/mobject/session/abstractmo.cpp
index bc00d335b..aeb4af956 100644
--- a/src/proc/mobject/session/abstractmo.cpp
+++ b/src/proc/mobject/session/abstractmo.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file abstractmo.cpp
- ** TODO abstractmo.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/abstractmo.hpp b/src/proc/mobject/session/abstractmo.hpp
index 986197a80..093cfaeef 100644
--- a/src/proc/mobject/session/abstractmo.hpp
+++ b/src/proc/mobject/session/abstractmo.hpp
@@ -22,7 +22,7 @@
 
 
 /** @file abstractmo.hpp
- ** TODO abstractmo.hpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/allocation.cpp b/src/proc/mobject/session/allocation.cpp
index 8532b12f3..3e8912eb7 100644
--- a/src/proc/mobject/session/allocation.cpp
+++ b/src/proc/mobject/session/allocation.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file allocation.cpp
- ** TODO allocation.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/allocation.hpp b/src/proc/mobject/session/allocation.hpp
index bc94389f4..6f6881422 100644
--- a/src/proc/mobject/session/allocation.hpp
+++ b/src/proc/mobject/session/allocation.hpp
@@ -22,7 +22,8 @@
 
 
 /** @file allocation.hpp
- ** TODO allocation.hpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet...
+ ** @deprecated WTF? looks like a leftover of some early brainstorming...
  */
 
 
diff --git a/src/proc/mobject/session/auto.cpp b/src/proc/mobject/session/auto.cpp
index 5b1032a1a..e3e0ede12 100644
--- a/src/proc/mobject/session/auto.cpp
+++ b/src/proc/mobject/session/auto.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file auto.cpp
- ** TODO auto.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/auto.hpp b/src/proc/mobject/session/auto.hpp
index 1f542e247..69136380b 100644
--- a/src/proc/mobject/session/auto.hpp
+++ b/src/proc/mobject/session/auto.hpp
@@ -22,7 +22,7 @@
 
 
 /** @file auto.hpp
- ** TODO auto.hpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/binding.cpp b/src/proc/mobject/session/binding.cpp
index b116252e2..7c85195e3 100644
--- a/src/proc/mobject/session/binding.cpp
+++ b/src/proc/mobject/session/binding.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file binding.cpp
- ** TODO binding.cpp
+ ** Implementation details of the Binding MObject to tie a sequence into a timeline or virtual clip
+ ** @todo stalled effort towards a session implementation from 2010
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/binding.hpp b/src/proc/mobject/session/binding.hpp
index 928ceec6d..1d9d638dc 100644
--- a/src/proc/mobject/session/binding.hpp
+++ b/src/proc/mobject/session/binding.hpp
@@ -22,7 +22,9 @@
 
 
 /** @file binding.hpp
- ** TODO binding.hpp
+ ** MObject in session to represent the top-level binding of a sequence
+ ** @todo stalled effort towards a session implementation from 2010
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/bus-mo.cpp b/src/proc/mobject/session/bus-mo.cpp
index 433a3f393..1f8faf21e 100644
--- a/src/proc/mobject/session/bus-mo.cpp
+++ b/src/proc/mobject/session/bus-mo.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file bus-mo.cpp
- ** TODO bus-mo.cpp
+ ** Implementation details for a _processing pipe_ representation in the Session model
+ ** @todo stalled effort towards a session implementation from 2010
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/bus-mo.hpp b/src/proc/mobject/session/bus-mo.hpp
index d00e764df..24f591539 100644
--- a/src/proc/mobject/session/bus-mo.hpp
+++ b/src/proc/mobject/session/bus-mo.hpp
@@ -22,7 +22,12 @@
 
 
 /** @file bus-mo.hpp
- ** TODO bus-mo.hpp
+ ** MObject in the Session to represent a processing pipe.
+ ** Within the Session model, Pipes are conceptual entities, which do not correspond
+ ** 1:1 to some render nodes, but rather help the _user_ to organise the processing steps
+ ** required to get some piece of the film into desired shape
+ ** @todo stalled effort towards a session implementation from 2010
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/clip.cpp b/src/proc/mobject/session/clip.cpp
index 8df40ec34..1016b6df1 100644
--- a/src/proc/mobject/session/clip.cpp
+++ b/src/proc/mobject/session/clip.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file clip.cpp
- ** TODO clip.cpp
+ ** Implementation details regarding a media clip as integrated into the edit / session model.
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
@@ -43,18 +45,18 @@ namespace session {
   /** new clip-MO linked with the given asset::Clip.
    *  Initially, this clip will cover the whole source media length.
    */
-  Clip::Clip (const asset::Clip& clipDef, const Media& mediaDef)
+  Clip::Clip (asset::Clip const& clipDef, Media const& mediaDef)
     : mediaDef_(mediaDef)
     , clipDef_(clipDef)
-  {
-    setupLength();
-    throwIfInvalid();
-  }
+    {
+      setupLength();
+      throwIfInvalid();
+    }
   
   
   
   /** implementing the common MObject self test.
-   *  Length definition is consitent, underlying
+   *  Length definition is consistent, underlying
    *  media def is accessible etc. */
   bool
   Clip::isValid ()  const
diff --git a/src/proc/mobject/session/clip.hpp b/src/proc/mobject/session/clip.hpp
index 6c1f39098..bd38df1fa 100644
--- a/src/proc/mobject/session/clip.hpp
+++ b/src/proc/mobject/session/clip.hpp
@@ -22,7 +22,9 @@
 
 
 /** @file clip.hpp
- ** TODO clip.hpp
+ ** MObject in the Session to represent a clip on the timeline
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/constraint.cpp b/src/proc/mobject/session/constraint.cpp
index b9e59aeb4..48cc7d6e4 100644
--- a/src/proc/mobject/session/constraint.cpp
+++ b/src/proc/mobject/session/constraint.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file constraint.cpp
- ** TODO constraint.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/constraint.hpp b/src/proc/mobject/session/constraint.hpp
index 9cdb3daee..766382064 100644
--- a/src/proc/mobject/session/constraint.hpp
+++ b/src/proc/mobject/session/constraint.hpp
@@ -22,7 +22,8 @@
 
 
 /** @file constraint.hpp
- ** TODO constraint.hpp
+ ** Specialised LocatingPin for use in placements
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/effect.cpp b/src/proc/mobject/session/effect.cpp
index 760ac9771..f4bac6756 100644
--- a/src/proc/mobject/session/effect.cpp
+++ b/src/proc/mobject/session/effect.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file effect.cpp
- ** TODO effect.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
@@ -38,7 +38,7 @@ namespace session {
   asset::Proc const& 
   Effect::getProcAsset() const
   {
-    UNIMPLEMENTED ("how to access the processing asset assotiated to a given Effect-MObject");
+    UNIMPLEMENTED ("how to access the processing asset associated to a given Effect-MObject");
   }
   
   
diff --git a/src/proc/mobject/session/effect.hpp b/src/proc/mobject/session/effect.hpp
index 133cf80ca..b54ed80b6 100644
--- a/src/proc/mobject/session/effect.hpp
+++ b/src/proc/mobject/session/effect.hpp
@@ -22,7 +22,7 @@
 
 
 /** @file effect.hpp
- ** TODO effect.hpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/element-query.hpp b/src/proc/mobject/session/element-query.hpp
index e10d2f81f..132b06317 100644
--- a/src/proc/mobject/session/element-query.hpp
+++ b/src/proc/mobject/session/element-query.hpp
@@ -22,7 +22,10 @@
 
 
 /** @file element-query.hpp
- ** TODO element-query.hpp
+ ** Search and query services to discover contents of the session
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/fixedlocation.cpp b/src/proc/mobject/session/fixedlocation.cpp
index 115fe56d0..4cc323da2 100644
--- a/src/proc/mobject/session/fixedlocation.cpp
+++ b/src/proc/mobject/session/fixedlocation.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file fixedlocation.cpp
- ** TODO fixedlocation.cpp
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/fixedlocation.hpp b/src/proc/mobject/session/fixedlocation.hpp
index d19a9e587..7790a00b8 100644
--- a/src/proc/mobject/session/fixedlocation.hpp
+++ b/src/proc/mobject/session/fixedlocation.hpp
@@ -22,7 +22,13 @@
 
 
 /** @file fixedlocation.hpp
- ** TODO fixedlocation.hpp
+ ** Specialised LocatingPin for use in Placement, especially for globally fixed positions
+ ** The FixedLocation is assumed to play a central role within the Build process, which
+ ** ultimately aims ad resolving any part of the session into either a wiring directive
+ ** or a piece of media or processing to happen at a location fixed in time.
+ ** 
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/fixture.cpp b/src/proc/mobject/session/fixture.cpp
index ce2f1bcd7..70b705580 100644
--- a/src/proc/mobject/session/fixture.cpp
+++ b/src/proc/mobject/session/fixture.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file fixture.cpp
- ** TODO fixture.cpp
+ ** Implementation of the Fixture datastructure
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/fixture.hpp b/src/proc/mobject/session/fixture.hpp
index 06cc74617..d4b489617 100644
--- a/src/proc/mobject/session/fixture.hpp
+++ b/src/proc/mobject/session/fixture.hpp
@@ -22,7 +22,21 @@
 
 
 /** @file fixture.hpp
- ** TODO fixture.hpp
+ ** Backbone data structure of the low-level render node model
+ ** The fixture defines the boundary between the Session (high-level) realm
+ ** and the internals of the render engine. The goal of a Builder run is to
+ ** build a new Fixture. All relative or indirect referrals are resolved at that point
+ ** and all time positions or output designations are made explicit. The Fixture defines
+ ** a Segmentation of every (top-level) timeline, and thus defines those segments which
+ ** can be rendered with a single wiring configuration. This Segmentation, as defined as
+ ** part of the Fixture, is also the foundation for memory management within the engine
+ ** model, since the allocation of render nodes for a given segment happens at once, and
+ ** segments are obliterated as a whole, when being replaced by a new version as result
+ ** of a more recent builder run. Ongoing render processes are also tracked per segment,
+ ** which allows the individual calculation steps just to assume the data is "there".
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/fork.cpp b/src/proc/mobject/session/fork.cpp
index 1d9a1e675..e6fd9b1ff 100644
--- a/src/proc/mobject/session/fork.cpp
+++ b/src/proc/mobject/session/fork.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file fork.cpp
- ** TODO fork.cpp
+ ** Implementation of the basic grouping device within the session ("Track" / "Media Bin")
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/fork.hpp b/src/proc/mobject/session/fork.hpp
index 73468e94e..01e6d93d8 100644
--- a/src/proc/mobject/session/fork.hpp
+++ b/src/proc/mobject/session/fork.hpp
@@ -22,7 +22,32 @@
 
 
 /** @file fork.hpp
- ** TODO fork.hpp
+ ** Organisational grouping device within the Session model ("Track" / "Media Bin").
+ ** Within Lumiera, Tracks bear no direct relation to the rendering or calculation process;
+ ** rather they are just conceived as a space for the user to arrange the parts included
+ ** into the edit.
+ ** 
+ ** A Fork is a nested tree-shaped structure. When integrated into a sequence, it will be
+ ** rendered in the familiar way, as tracks with media clips. But at the same time, when
+ ** accessed through the _Asset management view_ ("bookkeeping view"), a fork appears as
+ ** nested folder structure to hold media clips.
+ ** 
+ ** Most importantly, a Fork defines a _system of nested scopes._ When discovering details
+ ** of the wiring, setup and configuration, the Build process will look into the enclosing
+ ** scope to fill in any part not defined locally at a given media object. Go give a typical
+ ** example, the _volume for sound playback_ can be defined in some root scope, causing all
+ ** sound objects to _inherit_ that volume setting -- unless shadowed by a more specialised
+ ** setting closer in scope to the sound object in question. This allows to set up global
+ ** properties and then to override them locally, for a group of objects located in some
+ ** sub-fork.
+ ** 
+ ** @note to stress this point: in Lumiera we do _not conceive tracks as some kind of
+ **       channel, with media data flowing through the tracks._ Also, _tracks are not layers._
+ **       This also means, there is _no distinction in audio and video tracks._
+ **       We leave it at the user's discretion how she wants to organise the edit.
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/generator-mo.cpp b/src/proc/mobject/session/generator-mo.cpp
index 6e836a480..f7f56449e 100644
--- a/src/proc/mobject/session/generator-mo.cpp
+++ b/src/proc/mobject/session/generator-mo.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file generator-mo.cpp
- ** TODO generator-mo.cpp
+ ** @todo WIP implementation of player subsystem from 2011
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/generator-mo.hpp b/src/proc/mobject/session/generator-mo.hpp
index 059f012e7..35bef01af 100644
--- a/src/proc/mobject/session/generator-mo.hpp
+++ b/src/proc/mobject/session/generator-mo.hpp
@@ -22,7 +22,10 @@
 
 
 /** @file generator-mo.hpp
- ** TODO generator-mo.hpp
+ ** A data generator media object.
+ ** Can be used as placeholder, or as testing device
+ ** @todo WIP implementation of player subsystem from 2011
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/label.cpp b/src/proc/mobject/session/label.cpp
index a292a9de0..c83b90d87 100644
--- a/src/proc/mobject/session/label.cpp
+++ b/src/proc/mobject/session/label.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file label.cpp
- ** TODO label.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/label.hpp b/src/proc/mobject/session/label.hpp
index 906cb777b..ea6b5b3a4 100644
--- a/src/proc/mobject/session/label.hpp
+++ b/src/proc/mobject/session/label.hpp
@@ -22,7 +22,14 @@
 
 
 /** @file label.hpp
- ** TODO label.hpp
+ ** A marker or reference point in the Session.
+ ** Label MObjects can be [placed](\ref Placement) at various locations and scopes,
+ ** e.g. on the timeline, or relative to the media data of a clip. They can be used to give
+ ** a visual clue for the user's orientation within the edit, or for navigation on the timeline,
+ ** but also as an anchor point to place other elements with relative offset.
+ ** 
+ ** @todo result of the very first code generation from UML in 2008.
+ ** @todo this is expected to become a very important facility eventually, so expec a lot of rework here... 
  */
 
 
diff --git a/src/proc/mobject/session/locatingpin.cpp b/src/proc/mobject/session/locatingpin.cpp
index b0c29bbb3..11cfa8beb 100644
--- a/src/proc/mobject/session/locatingpin.cpp
+++ b/src/proc/mobject/session/locatingpin.cpp
@@ -22,7 +22,11 @@
 
 
 /** @file locatingpin.cpp
- ** TODO locatingpin.cpp
+ ** Implementation of the query resolving mechanics within a Placement.
+ ** All MObject entities within the session are attached via Placement,
+ ** and each such Placement holds a list of _constraints,_ represented as LocatingPin.
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/meta.cpp b/src/proc/mobject/session/meta.cpp
index 1a14a64bc..d0891b5f0 100644
--- a/src/proc/mobject/session/meta.cpp
+++ b/src/proc/mobject/session/meta.cpp
@@ -22,7 +22,10 @@
 
 
 /** @file meta.cpp
- ** TODO meta.cpp
+ ** implementation details regarding the Meta asset abstraction
+ ** 
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 not sure if we really need a separate translation unit for this?
  */
 
 
diff --git a/src/proc/mobject/session/meta.hpp b/src/proc/mobject/session/meta.hpp
index c5973dbe4..0cff68e6f 100644
--- a/src/proc/mobject/session/meta.hpp
+++ b/src/proc/mobject/session/meta.hpp
@@ -22,7 +22,9 @@
 
 
 /** @file meta.hpp
- ** TODO meta.hpp
+ ** Intermediate Asset interface: metadata and processing instructions
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/mobjectfactory.cpp b/src/proc/mobject/session/mobjectfactory.cpp
index 1941e73df..82e6bb764 100644
--- a/src/proc/mobject/session/mobjectfactory.cpp
+++ b/src/proc/mobject/session/mobjectfactory.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file mobjectfactory.cpp
- ** TODO mobjectfactory.cpp
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/mobjectfactory.hpp b/src/proc/mobject/session/mobjectfactory.hpp
index 16830e2d6..5edcefe3e 100644
--- a/src/proc/mobject/session/mobjectfactory.hpp
+++ b/src/proc/mobject/session/mobjectfactory.hpp
@@ -22,7 +22,10 @@
 
 
 /** @file mobjectfactory.hpp
- ** TODO mobjectfactory.hpp
+ ** Core factory to generate media objects for use in the Session model.
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework.
+ **       In fact I am quite unhappy with the shape of this code
  */
 
 
diff --git a/src/proc/mobject/session/placement-index-query-resolver.cpp b/src/proc/mobject/session/placement-index-query-resolver.cpp
index 8efc2606a..f7b5094e0 100644
--- a/src/proc/mobject/session/placement-index-query-resolver.cpp
+++ b/src/proc/mobject/session/placement-index-query-resolver.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file placement-index-query-resolver.cpp
- ** TODO placement-index-query-resolver.cpp
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/plug.cpp b/src/proc/mobject/session/plug.cpp
index d6b05b451..0b6520684 100644
--- a/src/proc/mobject/session/plug.cpp
+++ b/src/proc/mobject/session/plug.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file plug.cpp
- ** TODO plug.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/plug.hpp b/src/proc/mobject/session/plug.hpp
index f415825ed..f7d5f574f 100644
--- a/src/proc/mobject/session/plug.hpp
+++ b/src/proc/mobject/session/plug.hpp
@@ -22,7 +22,7 @@
 
 
 /** @file plug.hpp
- ** TODO plug.hpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
@@ -45,7 +45,7 @@ namespace session {
   class Plug : public Wish
     {
     protected:
-      /** the Pipe this MObject wants to be conected to */
+      /** the Pipe this MObject wants to be connected to */
       asset::Pipe* outPipe;   ////////////////////////////////TODO: shared_ptr
       
     };
diff --git a/src/proc/mobject/session/query-focus-stack.hpp b/src/proc/mobject/session/query-focus-stack.hpp
index 25bc775df..15d9e2625 100644
--- a/src/proc/mobject/session/query-focus-stack.hpp
+++ b/src/proc/mobject/session/query-focus-stack.hpp
@@ -22,7 +22,9 @@
 
 
 /** @file query-focus-stack.hpp
- ** TODO query-focus-stack.hpp
+ ** Implementation facility to work with and navigate nested scopes
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
@@ -52,7 +54,7 @@ namespace session {
    * a boost::intrusive_ptr, which stores the ref-count within
    * the mentioned ScopePath frames located in the stack.
    * 
-   * \par automatic cleanup of unused frames
+   * ## automatic cleanup of unused frames
    * 
    * The stack is aware of this ref-counting mechanism and will --
    * on each access -- automatically clean up any unused frames starting
@@ -199,4 +201,4 @@ namespace session {
   
   
 }}} // namespace mobject::session
-#endif
+#endif /*MOBJECT_SESSION_QUERY_FOCUS_STACK_H*/
diff --git a/src/proc/mobject/session/query-focus.cpp b/src/proc/mobject/session/query-focus.cpp
index f51f1e271..9d4baa51b 100644
--- a/src/proc/mobject/session/query-focus.cpp
+++ b/src/proc/mobject/session/query-focus.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file query-focus.cpp
- ** TODO query-focus.cpp
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/query-focus.hpp b/src/proc/mobject/session/query-focus.hpp
index dd68b74a9..da1987bd0 100644
--- a/src/proc/mobject/session/query-focus.hpp
+++ b/src/proc/mobject/session/query-focus.hpp
@@ -22,7 +22,25 @@
 
 
 /** @file query-focus.hpp
- ** TODO query-focus.hpp
+ ** Representation of the _current scope_ when navigating the session model.
+ ** Session contents may be discovered by query, and a _current location_ plays a crucial
+ ** role to fill in any missing details for resolving such a query. Thus, any code in need
+ ** to query contents or otherwise discover settings currently in effect within a given scope,
+ ** need to manage the position, where the query resolution is assumed to happen. The query focus
+ ** acts as an abstracted representation of such a location, and provides means for relative navigation.
+ ** The implementation involves a hidden service to record a movement trail, which allows to consider
+ ** the way how a some deeply nested scope was accessed. This information might be of relevance, due
+ ** to the ability to use _virtual clips_ recursively as part of the edit. Effectively, such means to
+ ** refer to some edit defined elsewhere in the session, and thus this feature turns the tree of nested
+ ** scopes into a *DAG* (directed acyclic graph). Such a structure can still be handled as if it was
+ ** a tree, but we need to take the access path into consideration: placing a given edit as virtual
+ ** clip into another scope will cause some properties not defined locally to be resolved in a
+ ** different way, depending on the context in which we encounter this virtual clip. To give an
+ ** example, the edited media might contain "sound", which needs to be panned and routed differently,
+ ** depending on the context the clip is placed into.
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
@@ -51,7 +69,7 @@ namespace session {
    * focus path locations. The intention is for this current location
    * to follow the ongoing query/discovery operations mostly automatically.
    * 
-   * \par usage
+   * # usage
    * 
    * A QueryFocus (frontend handle) can be default constructed, in which
    * case it will automatically connect to what is currently the focus
diff --git a/src/proc/mobject/session/query/fake-configrules.cpp b/src/proc/mobject/session/query/fake-configrules.cpp
index 492faeeb3..30c81ab7a 100644
--- a/src/proc/mobject/session/query/fake-configrules.cpp
+++ b/src/proc/mobject/session/query/fake-configrules.cpp
@@ -22,7 +22,17 @@
 
 
 /** @file fake-configrules.cpp
- ** TODO fake-configrules.cpp
+ ** Implementation of a fake query resolution service based on preconfigured answers.
+ ** Since we're not able to build or even integrate a real resolution engine for the time being,
+ ** we use a table of preconfigured answers, which allows us to handle the standard cases and
+ ** some additional unit test cases.
+ ** 
+ ** Obviously this is a dirty hack, and the implementation is a pile of spaghetti code,
+ ** hastily bashed together to keep things going. Typically this fake code collaborates with
+ ** backdoor functions placed into otherwise not yet implemented facilities, to get past the
+ ** roadblock. For example, StructFactory::made4fake()
+ ** 
+ ** @deprecated integrate a real resolution engine! /////////////////////////////////////////////////////////TICKET #710
  */
 
 
@@ -42,7 +52,7 @@
 using lib::Literal;
 using util::isnil;
 
-//////////////////////////////////////////////////////////////////TICKET #710 : to be removed entirely in Alpha
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////TICKET #710 : to be removed entirely in Alpha
 
 namespace proc {
 namespace mobject {
diff --git a/src/proc/mobject/session/relativelocation.cpp b/src/proc/mobject/session/relativelocation.cpp
index a5d258e2c..bcb2002d1 100644
--- a/src/proc/mobject/session/relativelocation.cpp
+++ b/src/proc/mobject/session/relativelocation.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file relativelocation.cpp
- ** TODO relativelocation.cpp
+ ** LocatingPin (constraint) to attach media objects relative to each other
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/relativelocation.hpp b/src/proc/mobject/session/relativelocation.hpp
index 52b466893..d106b0751 100644
--- a/src/proc/mobject/session/relativelocation.hpp
+++ b/src/proc/mobject/session/relativelocation.hpp
@@ -22,7 +22,8 @@
 
 
 /** @file relativelocation.hpp
- ** TODO relativelocation.hpp
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/root.cpp b/src/proc/mobject/session/root.cpp
index 612328ca9..dace7ce9a 100644
--- a/src/proc/mobject/session/root.cpp
+++ b/src/proc/mobject/session/root.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file root.cpp
- ** TODO root.cpp
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/root.hpp b/src/proc/mobject/session/root.hpp
index b2c42d0e4..ac56e9433 100644
--- a/src/proc/mobject/session/root.hpp
+++ b/src/proc/mobject/session/root.hpp
@@ -22,7 +22,15 @@
 
 
 /** @file root.hpp
- ** TODO root.hpp
+ ** MObject within the session to represent "the session itself".
+ ** The root object is used as anchor point when it comes to building, accessing
+ ** or displaying the whole session. Moreover, the placement used to attach the
+ ** Root MObejct into the session effectively represents the "global scope" -- any
+ ** constraint attached to this placement possibly effects any other object placed
+ ** anywhere within this global scope...
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/scope-locator.hpp b/src/proc/mobject/session/scope-locator.hpp
index 44264dff8..0d790d1f7 100644
--- a/src/proc/mobject/session/scope-locator.hpp
+++ b/src/proc/mobject/session/scope-locator.hpp
@@ -22,7 +22,9 @@
 
 
 /** @file scope-locator.hpp
- ** TODO scope-locator.hpp
+ ** Service to build the notion of a _current location_ within the Sesison model
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
@@ -52,7 +54,7 @@ namespace session {
   /**
    * Singleton service establishing a link to relate
    * any compound of nested placement scopes to the current session
-   * and the \em current focus for querying and exploring this structure.
+   * and the _current focus_ for querying and exploring this structure.
    * While it is OK to use this service directly, clients usually would
    * prefer to use QueryFocus as a frontend.
    * 
diff --git a/src/proc/mobject/session/scope-path.cpp b/src/proc/mobject/session/scope-path.cpp
index 6b17996b5..00c1f0266 100644
--- a/src/proc/mobject/session/scope-path.cpp
+++ b/src/proc/mobject/session/scope-path.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file scope-path.cpp
- ** TODO scope-path.cpp
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/scope.hpp b/src/proc/mobject/session/scope.hpp
index 10966f840..f25eea594 100644
--- a/src/proc/mobject/session/scope.hpp
+++ b/src/proc/mobject/session/scope.hpp
@@ -22,7 +22,8 @@
 
 
 /** @file scope.hpp
- ** TODO scope.hpp
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/segment.cpp b/src/proc/mobject/session/segment.cpp
index 2bdb5071e..9f601809a 100644
--- a/src/proc/mobject/session/segment.cpp
+++ b/src/proc/mobject/session/segment.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file segment.cpp
- ** TODO segment.cpp
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 #include "proc/mobject/session/segment.hpp"
diff --git a/src/proc/mobject/session/segment.hpp b/src/proc/mobject/session/segment.hpp
index ab094d934..7eba07412 100644
--- a/src/proc/mobject/session/segment.hpp
+++ b/src/proc/mobject/session/segment.hpp
@@ -22,7 +22,9 @@
 
 
 /** @file segment.hpp
- ** TODO segment.hpp
+ ** Building block of the backbone of the low-level (render node) model
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/segmentation.cpp b/src/proc/mobject/session/segmentation.cpp
index e13d75bef..0a8d9c721 100644
--- a/src/proc/mobject/session/segmentation.cpp
+++ b/src/proc/mobject/session/segmentation.cpp
@@ -22,7 +22,8 @@
 
 
 /** @file segmentation.cpp
- ** TODO segmentation.cpp
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 #include "proc/mobject/session/segmentation.hpp"
diff --git a/src/proc/mobject/session/segmentation.hpp b/src/proc/mobject/session/segmentation.hpp
index f69baf58d..047ced48b 100644
--- a/src/proc/mobject/session/segmentation.hpp
+++ b/src/proc/mobject/session/segmentation.hpp
@@ -22,7 +22,14 @@
 
 
 /** @file segmentation.hpp
- ** TODO segmentation.hpp
+ ** A segment of the effective timeline, part of the low-level model backbone.
+ ** Within the Fixture, a Segment of the timeline is used as attachment point for all the
+ ** render nodes relevant for rendering this segment. Thus, the Segmentation defines the
+ ** index and access datastructure to get at any point of the render node network.
+ ** Moreover, the segments are used as foundation for render node memory management
+ ** 
+ ** @todo stalled effort towards a session implementation from 2008
+ ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
 
diff --git a/src/proc/mobject/session/sess-manager-impl.cpp b/src/proc/mobject/session/sess-manager-impl.cpp
index 4bdd00317..452fe23ae 100644
--- a/src/proc/mobject/session/sess-manager-impl.cpp
+++ b/src/proc/mobject/session/sess-manager-impl.cpp
@@ -29,7 +29,7 @@
  ** access via his overloaded operator->() . Because there is no operator*(),
  ** no one can get at the address of the current session object. (correct?)
  **
- ** TODO: this is an implementation draft, awaiting integration with several other facilities //////////////////TICKET #704
+ ** @todo as of 2016 this is an implementation draft, awaiting integration with several other facilities //////////////////TICKET #704
  **
  ** @see session-impl.hpp
  ** @see mobject::Session#current
diff --git a/src/proc/mobject/session/sess-manager-impl.hpp b/src/proc/mobject/session/sess-manager-impl.hpp
index 9dc6c5e58..384b9b506 100644
--- a/src/proc/mobject/session/sess-manager-impl.hpp
+++ b/src/proc/mobject/session/sess-manager-impl.hpp
@@ -22,7 +22,18 @@
 
 
 /** @file sess-manager-impl.hpp
- ** TODO sess-manager-impl.hpp
+ ** Implementation facility for session management.
+ ** Users are assumed to access the session itself through a smart-ptr, which happens
+ ** to be the SessManager. Thus, accessing this front-end directly allows to invoke the
+ ** typical lifecycle and management operations (open, close, save, load). Since the
+ ** Session plays such a central role, we obviously want to expose just an interface
+ ** to client code, both regarding the Session itself, and the session manager.
+ ** 
+ ** The SessManagerImpl involves the LifecylceAdvisor, which holds all the logic to
+ ** manage start-up and shutdown of the session, including starting of the core services
+ ** and opening of the external facade interfaces.
+ ** 
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/session-impl.cpp b/src/proc/mobject/session/session-impl.cpp
index 34f90b345..40c00d68b 100644
--- a/src/proc/mobject/session/session-impl.cpp
+++ b/src/proc/mobject/session/session-impl.cpp
@@ -22,7 +22,9 @@
 
 
 /** @file session-impl.cpp
- ** TODO session-impl.cpp
+ ** Implementation of the global session datastructure
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/session-services.cpp b/src/proc/mobject/session/session-services.cpp
index 2994660d6..167daefbb 100644
--- a/src/proc/mobject/session/session-services.cpp
+++ b/src/proc/mobject/session/session-services.cpp
@@ -22,7 +22,22 @@
 
 
 /** @file session-services.cpp
- ** TODO session-services.cpp
+ ** Implementation of some top-level internal services of the session.
+ ** The Session is _the_ central interface to access the model and thus the
+ ** edit being worked on. Behind the scenes, it needs to operate several technically
+ ** quite involved services, which we prefer to hide away as implementation details.
+ ** Typically, each of these services defines a dedicated interface, and is implemented
+ ** by delegating to a set of more specialised facilities.
+ ** 
+ ** The following services are integrated here
+ ** - service to access a Placement by (hash) ID
+ ** - service to attach or remove session content, while maintaining all indices
+ ** - service to query and explore session contents
+ ** - service to inject mock content for unit testing
+ ** - service to manage and discover default settings by resolution query
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/specific-contents-query.hpp b/src/proc/mobject/session/specific-contents-query.hpp
index fea11cccc..08303fae3 100644
--- a/src/proc/mobject/session/specific-contents-query.hpp
+++ b/src/proc/mobject/session/specific-contents-query.hpp
@@ -22,7 +22,12 @@
 
 
 /** @file specific-contents-query.hpp
- ** TODO specific-contents-query.hpp
+ ** Implementation facility to query and retrieve session context with filtering conditions.
+ ** Client code is assumed to use the QueryResolver front-end and the SessionServiceExploreScope
+ ** as access point.
+ ** 
+ ** @todo WIP implementation of session core from 2010
+ ** @todo as of 2016, this effort is considered stalled but basically valid
  */
 
 
diff --git a/src/proc/mobject/session/wish.cpp b/src/proc/mobject/session/wish.cpp
index 58f688e51..dd538ca65 100644
--- a/src/proc/mobject/session/wish.cpp
+++ b/src/proc/mobject/session/wish.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file wish.cpp
- ** TODO wish.cpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 
 
diff --git a/src/proc/mobject/session/wish.hpp b/src/proc/mobject/session/wish.hpp
index aaffbc3a5..3b3c27392 100644
--- a/src/proc/mobject/session/wish.hpp
+++ b/src/proc/mobject/session/wish.hpp
@@ -22,7 +22,8 @@
 
 
 /** @file wish.hpp
- ** TODO wish.hpp
+ ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet...
+ ** @deprecated WTF?
  */