add TODO markers regarding #959

Some parts of the GUI model will be remoulded

src/gui/controller/controller.hpp

@@ -20,8 +20,10 @@
 
 */
 
-/** @file controller/controller.hpp
- ** This file contains the definition of the controller object
+/** @file controller.hpp
+ ** The top level UI controller.
+ ** 
+ ** @todo as of 1/2015, this needs to be reshaped ////////////////////TICKET #959
  */
 
 
@@ -40,6 +42,9 @@ class Project;
   
 namespace controller { 
 
+/**
+ * @todo needs to be reshaped for communication with Proc-Layer /////////////////TICKET #959
+ */
 class Controller
 {
 public:

src/gui/gtk-lumiera.cpp

@@ -84,6 +84,9 @@ GtkLumiera::application()
 
 
 
+/**
+ * @remarks this function blocks until shutdown of the UI
+ */
 void
 GtkLumiera::main (int argc, char *argv[])
 {

src/gui/gtk-lumiera.hpp

@@ -68,7 +68,7 @@ using std::shared_ptr;
 /* ====== The Application Class ====== */
 
 /**
- *  The main application class.
+ *  Top level entry point: The Lumiera GTK UI.
  */
 class GtkLumiera
   : boost::noncopyable
@@ -83,6 +83,7 @@ class GtkLumiera
     
     
     
+    /** start up the GUI and run the event thread */
     void main(int argc, char *argv[]);
     
     WindowManager& windowManager();

src/gui/model/project.hpp

@@ -22,7 +22,10 @@
 
 /** @file project.hpp
  ** This file contains the definition of Project, a class which
- ** stores project data, and wraps proc layer data
+ ** stores project data, and wraps proc layer data.
+ ** 
+ ** @todo this solution was used to build the first outline of the UI.
+ **       It needs to be reshaped into a connector to Proc-Layer  ///////////////TICKET #959
  */
 
 #ifndef PROJECT_HPP
@@ -35,6 +38,9 @@
 namespace gui {
 namespace model {
   
+/**
+ * @deprecated 1/2015 see TICKET #959
+ */
 class Project
 {
 public:

wiki/renderengine.html

@@ -2282,7 +2282,7 @@ Thus, the Proc-Layer exposes (one or several) facade interfaces for the GUI to u
 
 Probably the most important aspect regarding the GUI integration is how to get [[access to and operate on the Session|SessionInterface]]. More specifically, this includes [[referring to individual objects|MObjectRef]]. On top of these generic access mechanisms, we create a [[proxy GUI model|GuiModel]] for binding. The interface of this GUI model is tailored for display and translation into UI entities.</pre>
 </div>
-<div title="GuiModel" creator="Ichthyostega" modifier="Ichthyostega" created="201410170142" modified="201410270246" tags="GuiIntegration design draft" changecount="7">
+<div title="GuiModel" creator="Ichthyostega" modifier="Ichthyostega" created="201410170142" modified="201501051037" tags="GuiIntegration design draft" changecount="8">
 <pre>Building a layered architecture is a challenge, since the lower layer //really// needs to be self-contained, while prepared for usage by the higher layer.
 A major fraction of all desktop applications is written in a way where operational logic is built around the invocation from UI events -- what should be a shell turns into a backbone. One possible way to escape from this common anti pattern is to introduce a mediating entity, to translate between two partially incompatible demands and concerns: Sure, the &quot;tangible stuff&quot; is what matters, but you can not build any significant piece of technology if all you want is to &quot;serve&quot; the user.
 
@@ -2293,10 +2293,10 @@ The GUI model is largely comprised of immutable ID elements, which can be treate
 !synchronisation guarantees
 We acknowledge that the gui model is typically used from within the GUI event dispatch thread. This is //not// the thread where any session state is mutated. Thus it is the responsibility of this proxying model within the GUI to ensure that the retrieved structure is a coherent snapshot of the session state. Especially the {{{gui::model::SessionFacade}}} ensures that there was a read barrier between the state retrieval and any preceding mutation command. Actually, this is implemented down in Proc-Layer, with the help of the ProcDispatcher.
 
-Forwarding the model changes to the GUI widgets is another concern, since notifications from session mutations arrive asynchronous after each [[Builder]] run. In this case, we send a notification to the widgets registered as listeners, but wait for //them// to call back and fetch the [[diffed state|TreeDiffModel]]. This callback will be scheduled by the  widgets to perform in the GUI event  thread.
+The forwarding of model changes to the GUI widgets is another concern, since notifications from session mutations arrive asynchronous after each [[Builder]] run. In this case, we send a notification to the widgets registered as listeners, but wait for //them// to call back and fetch the [[diffed state|TreeDiffModel]]. This callback will be scheduled by the  widgets to perform in the GUI event  thread.
 </pre>
 </div>
-<div title="GuiModelUpdate" creator="Ichthyostega" modifier="Ichthyostega" created="201410250121" modified="201501031058" tags="GuiIntegration GuiPattern design decision discuss draft" changecount="21">
+<div title="GuiModelUpdate" creator="Ichthyostega" modifier="Ichthyostega" created="201410250121" modified="201501051031" tags="GuiIntegration GuiPattern design decision discuss draft" changecount="22">
 <pre>Considerations regarding the [[structure of custom timeline widgets|GuiTimelineWidgetStructure]] highlight again the necessity of a clean separation of concerns and an &quot;open closed design&quot;. For the purpose of updating the timeline(s) to reflect the HighLevelModel in Proc-Layer, several requirements can be identified
 * we need incremental updates: we must not start redrawing each and everything on each tiny change
 * we need recursive programming, since this is the only sane way to deal with tree like nested structures.
@@ -2315,7 +2315,7 @@ Hereby we introduce a new in-layer abstraction.
 * It performs in the GTK event thread.
 * no synchronisation is necessary
 * use constant values as far as possible
-* the UI bus is offered by the GUI model.
+* the UI bus is offered by the GuiModel.
 * it is //owned// by the GUI model.
 * there is a global &quot;kill switch&quot;. If toggled &quot;off&quot; any invocation is NOP.
 * thus there is no need for any ownership or resource tracking