MERGE Doxygen clean-up done during the last months

src/backend/backend.c

@@ -21,6 +21,11 @@
 * *****************************************************/
 
 
+/** @file backend.c
+ ** Lumiera Backend: implementation of global initialisation and services.
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 #include "lib/tmpbuf.h"

src/backend/backend.h

@@ -21,6 +21,11 @@
 */
 
 
+/** @file backend.h
+ ** Lumiera Backend: global initialisation and definitions.
+ */
+
+
 #ifndef BACKEND_BACKEND_H
 #define BACKEND_BACKEND_H
 

src/backend/engine/engine-config.cpp

@@ -21,6 +21,11 @@
 * *****************************************************/
 
 
+/** @file engine-config.cpp
+ ** implementation of engine configuration and parametrisation
+ */
+
+
 #include "backend/engine/engine-config.h"
 #include "lib/time/timevalue.hpp"
 

src/backend/engine/engine-config.h

@@ -21,6 +21,11 @@
 */
 
 
+/** @file engine-config.h
+ ** access point to configuration of engine parameters
+ */
+
+
 #ifndef BACKEND_ENGINE_ENGINE_CONFIG_H
 #define BACKEND_ENGINE_ENGINE_CONFIG_H
 

src/backend/engine/job.h

@@ -27,12 +27,12 @@
  ** for time bound invocation. This header defines the data structures used to describe
  ** a job, and the basic data structures used by the scheduler to keep track of individual
  ** jobs. Moreover, within the C++ part of this header, some classes are layered on top
- ** of these data structures; especially the JobClosure ABC describes the \em generic part
+ ** of these data structures; especially the JobClosure ABC describes the _generic part_
  ** of each job, while the "moving parts" are embedded within the lumiera_jobParameter.
  ** 
  ** A render job is a parameterless function, ready to be invoked by the scheduler..
  ** Since every non trivial job actually needs some parameters (at least a frame number)
- ** and relies on additional definitions and data structures, a \em closure is created
+ ** and relies on additional definitions and data structures, a _closure_ is created
  ** to make these dependencies explicit and opaque for the scheduler. The actual
  ** job invocation is forwarded to a virtual function JobClosure#invokeJobOperation(JobParameter),
  ** which is defined "somewhere" in a subclass and remains opaque for the scheduler;

src/backend/engine/scheduler-frontend.cpp

@@ -21,6 +21,11 @@
 * *****************************************************/
 
 
+/** @file scheduler-frontend.cpp
+ ** Scheduler service implementation
+ */
+
+
 #include "lib/error.h"
 #include "backend/engine/scheduler-frontend.hpp"
 

src/backend/engine/scheduler-frontend.hpp

@@ -21,6 +21,12 @@
 */
 
 
+/** @file scheduler-frontend.hpp
+ ** Scheduler service access point for higher layers.
+ ** @todo WIP unfinished since 9/2013
+ */
+
+
 #ifndef BACKEND_ENGINE_SCHEDULER_FRONTEND_H
 #define BACKEND_ENGINE_SCHEDULER_FRONTEND_H
 

src/backend/enginefacade.cpp

@@ -21,6 +21,17 @@
 * *****************************************************/
 
 
+/** @file enginefacade.cpp
+ ** Subsystem descriptor and configuration for the render engine.
+ ** This is the implementation part to manage render engine lifecycle
+ ** as a Subsystem of the whole application.
+ ** 
+ ** @todo placeholder/draft as of 1/2017
+ ** @see main.cpp
+ ** 
+ */
+
+
 #include "backend/enginefacade.hpp"
 #include "lib/depend.hpp"
 

src/backend/enginefacade.hpp

@@ -21,6 +21,14 @@
 */
 
 
+/** @file enginefacade.hpp
+ ** Global control interface for the render engine subsystem.
+ ** The render engine, as implemented in an combined effort by the
+ ** Lumiera backend and some parts of Proc-Layer, can be started and
+ ** stopped as a [Subsystem](\ref subsys.hpp) of the whole application.
+ */
+
+
 #ifndef BACKEND_INTERFACE_ENGINEFACADE_H
 #define BACKEND_INTERFACE_ENGINEFACADE_H
 

src/backend/file-handling.c

@@ -21,6 +21,11 @@
 * *****************************************************/
 
 
+/** @file file-handling.c
+ ** Implementation of file management functions
+ */
+
+
 #include "include/logging.h"
 #include "lib/mutex.h"
 #include "lib/safeclib.h"

src/backend/filedescriptor.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file filedescriptor.c
+ ** Implementation of a file descriptor management framework
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/mutex.h"
 #include "lib/safeclib.h"
@@ -78,7 +84,7 @@ lumiera_filedescriptor_acquire (const char* name, int flags, LList filenode)
                 }
               int fd;
               INFO (filedescriptor_dbg, "try creating file: %s", name);
-              TODO ("creat mode from config");
+              TODO ("create mode from config");
               fd = creat (name, 0666);
               if (fd == -1)
                 {

src/backend/filedescriptorregistry.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file filedescriptorregistry.c
+ ** Implementation of a registry to manage used filedescriptors
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 #include "lib/mutex.h"

src/backend/filehandle.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file filehandle.c
+ ** Implementation of filehandle representation.
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/llist.h"
 #include "lib/safeclib.h"

src/backend/filehandlecache.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file filehandlecache.c
+ ** Implementation of caching for filehandle representation data
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 

src/backend/fileheader.c

@@ -21,6 +21,13 @@
 * *****************************************************/
 
 
+/** @file fileheader.c
+ ** Implementation of a common header format for working data files created
+ ** by the lumiera backend.
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "lib/tmpbuf.h"
 
 #include "backend/fileheader.h"

src/backend/media-access-facade.cpp

@@ -21,6 +21,14 @@
 * *****************************************************/
 
 
+/** @file media-access-facade.cpp
+ ** Implementation binding to query for a media file's properties.
+ ** 
+ ** @todo this was added as a draft and mock implementation in 2008
+ **       and is only used sporadic for unit tests.
+ */
+
+
 #include "backend/media-access-facade.hpp"
 
 #include "lib/util.hpp"

src/backend/media-access-facade.hpp

@@ -21,6 +21,17 @@
 */
 
 
+/** @file media-access-facade.hpp
+ ** Abstraction interface to query for a media file.
+ ** The corresponding service allows to discover some properties like
+ ** the kind and number of channels for a given file (name) ID, without
+ ** touching any of the technical details related to file handling.
+ ** 
+ ** @todo this was added as a draft and mock implementation in 2008
+ **       and is only used sporadic for unit tests.
+ */
+
+
 #ifndef BACKEND_INTERFACE_MEDIA_ACCESS_FACADE_H
 #define BACKEND_INTERFACE_MEDIA_ACCESS_FACADE_H
 

src/backend/mmap.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file mmap.c
+ ** Implementation of management for memory mapped file regions
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 

src/backend/mmapcache.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file mmapcache.c
+ ** Implementation of caching for currently unused memory mapped file regions
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 

src/backend/mmapings.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file mmapings.c
+ ** Implementation of organisational data of memory mapped file regions
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/mutex.h"
 #include "lib/safeclib.h"

src/backend/netnodefacade.cpp

@@ -21,6 +21,14 @@
 * *****************************************************/
 
 
+/** @file netnodefacade.cpp
+ ** Subsystem descriptor and configuration for a renderfarm node.
+ ** 
+ ** @todo this just documents a vague plan. We won't be able to implement
+ **       anything of that kind for the foreseeable future as of 1/2017
+ */
+
+
 #include "backend/netnodefacade.hpp"
 #include "lib/depend.hpp"
 

src/backend/netnodefacade.hpp

@@ -21,6 +21,14 @@
 */
 
 
+/** @file netnodefacade.hpp
+ ** Global control interface for running Lumiera as a renderfarm node.
+ ** 
+ ** @todo this just documents a vague plan. We won't be able to implement
+ **       anything of that kind for the foreseeable future as of 1/2017
+ */
+
+
 #ifndef BACKEND_INTERFACE_NETNODEFACADE_H
 #define BACKEND_INTERFACE_NETNODEFACADE_H
 

src/backend/real-clock.cpp

@@ -1,5 +1,5 @@
 /*
-  Timings  -  timing specifications for a frame quantised data stream
+  RealClock  -  convenience front-end to access the system clock
 
   Copyright (C)         Lumiera.org
     2012,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,6 +21,16 @@
 * *****************************************************/
 
 
+/** @file real-clock.cpp
+ ** Implementation of simplified access to the current wall clock time.
+ ** 
+ ** @todo just a rough draft as of 2012 / 2017
+ ** @todo the idea was that the backend has elaborate knowledge about
+ **       timings and time progression; upper layers should thus be able
+ **       to fulfil their timing needs by querying the backend
+ */
+
+
 #include "backend/real-clock.hpp"
 
 #include <ctime>

src/backend/resourcecollector.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file resourcecollector.c
+ ** Implementation of a global service to manage scarce system resources
+ ** @todo this was a plan from 2008 and never got beyond an initial concept stage
+ */
+
+
 #include "include/logging.h"
 #include "lib/llist.h"
 #include "lib/mutex.h"

src/backend/resourcecollector.h

@@ -21,6 +21,12 @@
 */
 
 
+/** @file resourcecollector.h
+ ** A global manager for scarce system resources
+ ** @todo this was a plan from 2008 and never got beyond an initial concept stage
+ */
+
+
 #ifndef BACKEND_RESOURCECOLLECTOR_H
 #define BACKEND_RESOURCECOLLECTOR_H
 

src/backend/scriptrunnerfacade.cpp

@@ -21,6 +21,15 @@
 * *****************************************************/
 
 
+/** @file scriptrunnerfacade.cpp
+ ** Subsystem descriptor and configuration for a controlling and operating
+ ** Lumiera through bindings to a script language.
+ ** 
+ ** @todo this just documents a vague plan. We won't be able to implement
+ **       anything of that kind for the foreseeable future as of 1/2017
+ */
+
+
 #include "backend/scriptrunnerfacade.hpp"
 #include "lib/depend.hpp"
 

src/backend/scriptrunnerfacade.hpp

@@ -21,6 +21,14 @@
 */
 
 
+/** @file scriptrunnerfacade.hpp
+ ** Global control interface for script driven operation of Lumiera.
+ ** 
+ ** @todo this just documents a vague plan. We won't be able to implement
+ **       anything of that kind for the foreseeable future as of 1/2017
+ */
+
+
 #ifndef BACKEND_INTERFACE_SCRIPTRUNNERFACADE_H
 #define BACKEND_INTERFACE_SCRIPTRUNNERFACADE_H
 

src/backend/thread-wrapper.hpp

@@ -22,8 +22,22 @@
 */
 
 
-#ifndef LIB_THREAD_WRAPPER_H
+/** @file thread-wrapper.hpp
-#define LIB_THREAD_WRAPPER_H
+ ** Convenience front-end for basic thread handling needs.
+ ** The Lumiera backend contains a dedicated low-level thread handling framework,
+ ** which is relevant for scheduling render activities to make best use of parallelisation
+ ** abilities of the given system. Typically, the upper layers should not have to deal much
+ ** with thread handling, yet at some point there is the need to implement a self contained
+ ** action running within a dedicated thread. The backend::Thread class is a wrapper to
+ ** represent such an parallel action conveniently and safely; together with the object
+ ** monitor, this allows to abstract away intricacies into self contained objects.
+ ** 
+ ** @note the thread wrapper is not intended for high performance computations.
+ */
+
+
+#ifndef LIB_THREADWRAPPER_H
+#define LIB_THREADWRAPPER_H
 
 
 #include "lib/error.hpp"
@@ -280,4 +294,4 @@ namespace backend {
   
   
 } // namespace backend
-#endif /*LIB_THREAD_WRAPPER_H*/
+#endif /*LIB_THREADWRAPPER_H*/

src/backend/threadpool-init.cpp

@@ -21,6 +21,11 @@
 * *****************************************************/
 
 
+/** @file threadpool-init.cpp
+ ** Implementation of automatic initialisation of the low-level thread handling framework.
+ */
+
+
 #include "backend/threadpool-init.hpp"
 
 

src/backend/threadpool-init.hpp

@@ -22,7 +22,7 @@
 */
 
 /** @file threadpool-init.hpp
- ** Automatically bring up the Threading management and Threadpool in the backend.
+ ** Automatically bring up the threading management and threadpool in the backend.
  ** This works by registering a lifecycle callback, which is activated at the start
  ** of main or when running the testsuite. Similarly, a shutdown hook is registered.
  ** 

src/backend/threadpool.c

@@ -21,6 +21,13 @@
 * *****************************************************/
 
 
+/** @file threadpool.c
+ ** Implementation of a threadpool.
+ ** The plan is to manage the massively parallel activities by a scheduler.
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 #include "backend/threadpool.h"

src/backend/threadpool.h

@@ -21,6 +21,11 @@
 */
 
 
+/** @file threadpool.h
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #ifndef BACKEND_THREADPOOL_H
 #define BACKEND_THREADPOOL_H
 

src/backend/threads.c

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file threads.c
+ ** Implementation of Lumiera's low-level thread handling framework
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 #include "backend/threads.h"

src/backend/threads.h

@@ -21,6 +21,14 @@
 */
 
 
+/** @file threads.h
+ ** Lumiera low-level thread handling framework.
+ ** Exposed a limited set of operations to deal with parallelism,
+ ** while threads and thread creation is managed by a threadpool.
+ ** @todo development in this area is stalled since 2010
+ */
+
+
 #ifndef BACKEND_THREADS_H
 #define BACKEND_THREADS_H
 

src/common/advice/advice.cpp

@@ -22,7 +22,7 @@
 
 
 /** @file advice.cpp 
- ** Implementation the AdviceSystem, to support the advice collaboration.
+ ** Implementation of the AdviceSystem, to support the advice collaboration.
  ** The AdviceSystem is implemented as singleton, but is never accessed directly
  ** by clients participating in an advice collaboration. Rather, they use the
  ** advice::Request and advice::Provision value classes as a frontend. While
@@ -32,7 +32,7 @@
  ** implemented in this compilation unit and access the AdviceSystem singleton
  ** defined here locally.
  ** 
- ** \par memory management
+ ** ## memory management
  ** Advice data, when added by an advice::Provision, is copied into a ActiveProvision,
  ** which acts as a value holding buffer. This way, the provided advice data is copied
  ** into storage managed by the AdviceSystem, allowing to access the data even after the
@@ -53,7 +53,7 @@
  ** @note when a Provision is copied, this hidden link is not shared with the copy, which
  ** therefore behaves as if newly created with the same binding, but without providing Advice.
  ** 
- ** \par implementing the allocations
+ ** ## implementing the allocations
  ** The problem with copying and incorporating the ActiveProvision objects is the undetermined
  ** size of these value holders, because the frontend objects are templated on the advice type,
  ** while the AdviceSystem doesn't have any knowledge of the specific advice type. This advice
@@ -73,7 +73,7 @@
  ** 
  ** @todo rewrite the allocation to use Lumiera's MPool instead of heap allocations    //////TICKET #609
  ** 
- ** \par synchronisation
+ ** ## synchronisation
  ** While the frontend objects are deliberately \em not threadsafe, the lookup implementation
  ** within the AdviceSystem uses a system wide advice::Index table and thus needs locking.
  ** Besides the protection against corrupting the index, this also serves as memory barrier,

src/common/advice/binding.cpp

@@ -21,6 +21,15 @@
 * *****************************************************/
 
 
+/** @file binding.cpp
+ ** Implementation of a binding record to represent a match between two patterns.
+ ** This is used for the Advice System, to record existing connections between
+ ** advice providers and consumers. But as such, Binding is a generic mechanism
+ ** and looks like it could be of wider use within the Lumiera application.
+ ** This is the reason why Binding got a separate implementation `cpp` file.
+ */
+
+
 #include "lib/util.hpp"
 #include "lib/symbol.hpp"
 #include "common/advice/binding.hpp"
@@ -57,7 +66,7 @@ namespace advice {
     const string matchArg = "\\(\\s*"+matchSym+"?\\s*\\)"; 
     regex findPredicate ("\\s*"+matchSym+"("+matchArg+")?\\s*,?");    ///< \c sym(arg), groups: [symbol, parenthesis, argument symbol]
     
-    /** detect the \em arity of an predicate, as matched by #findPredicate.
+    /** detect the _arity_ of an predicate, as matched by #findPredicate.
      *  Currently, we don't really parse predicate logic notation and thus we
      *  just distinguish nullary predicates (no argument) and predicates with
      *  one single constant argument. */

src/common/advice/binding.hpp

@@ -30,7 +30,7 @@
  ** each specifying a binding, they can be paired up if any condition included into the binding
  ** holds true for both sides.
  ** 
- ** Typically, a binding includes a \em type-guard predicate \c advice.type.xx where \c xx is an 
+ ** Typically, a binding includes a _type-guard predicate_ `advice.type.xx` where `xx` is an
  ** identifier denoting a type used within an instantiation of the Advice collaboration, i.e. a type
  ** used as advice value in a instantiation of the PointOfAdvice<AD> template. Besides the type guard,
  ** a binding may narrow down the topic of the advice by providing further predicates. This allows for
@@ -41,7 +41,7 @@
  ** the advice type, and another client entity (the advised entity) could pick up this value
  ** without the need to now anything about the advisor.
  ** 
- ** \par implementation notes
+ ** # implementation notes
  ** Any binding will be normalised prior to further processing. This normalisation is based
  ** on ordering by predicate symbol and arity. Patterns just comprised of constant symbols
  ** (nullary atoms) can even be condensed into a single hash value, which allows for fast
@@ -56,7 +56,7 @@
  ** functor, the full pattern definition can be discarded.
  ** 
  ** @remarks while binding is defined in the context of the advice system for now,
- **       obviously this is the foundation of a more generic system to deal with predicate terms. 
+ **       obviously this is the foundation of a more generic system to deal with predicate terms.
  ** @note as of 4/2010 this is an experimental setup and implemented just enough to work out
  **       the interfaces. Ichthyo expects this collaboration service to play a central role
  **       at various places within proc-layer.

src/common/appstate.cpp

@@ -1,5 +1,5 @@
 /*
-  AppState  -  application initialisation and behaviour 
+  AppState  -  application initialisation and behaviour
 
   Copyright (C)         Lumiera.org
     2008,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,6 +21,17 @@
 * *****************************************************/
 
 
+/** @file appstate.cpp
+ ** Implementation of the _main application object_ of Lumiera.
+ ** This is a service to manage some _really global_ state and to
+ ** organise, start and stop the ["Subsystems"](\ref subsys.hpp).
+ ** The AppState object provides the building blocks for the
+ ** `main()` function to control the global lifecycle.
+ ** 
+ ** @see main.cpp
+ */
+
+
 #include "lib/error.hpp"
 #include "include/lifecycle.h"
 #include "common/appstate.hpp"

src/common/appstate.hpp

@@ -1,5 +1,5 @@
 /*
-  APPSTATE.hpp  -  application initialisation and behaviour 
+  APPSTATE.hpp  -  application initialisation and behaviour
 
   Copyright (C)         Lumiera.org
     2008,               Hermann Vosseler <Ichthyostega@web.de>

src/common/basic-setup.cpp

@@ -21,6 +21,18 @@
 * *****************************************************/
 
 
+/** @file basic-setup.cpp
+ ** Implementation of self-configuration and bootstrap functionality.
+ ** This allows the application to "find its parts" at startup.
+ ** @note as of 2016, BasicSetup::BasicSetup(string) also reads
+ **       and evaluates a simple `*.ini` file to provide a
+ **       preliminary mechanism for application configuration.
+ **       This implementation is based on Boost program options
+ ** 
+ ** @see searchpath.hpp
+ */
+
+
 #include "common/basic-setup.hpp"
 #include "lib/searchpath.hpp"
 #include "lib/error.hpp"

src/common/basic-setup.hpp

@@ -21,6 +21,35 @@
 */
 
 
+/** @file basic-setup.hpp
+ ** Bootstrap and self-configuration of the application at startup.
+ ** The class BasicSetup represents the very basic self-configuration
+ ** of the application at start-up. This bootstrap is based on some
+ ** conventions for the application to "find its parts".
+ ** 
+ ** # Motivation: why a bootstrap convention?
+ ** We want Lumiera to be usable _without the need of a set-up._
+ ** Since the application is meant to be used in media production, users
+ ** often have to work in temporary and varying environments. In such a
+ ** situation, it is desirable just to "unzip and start" an application
+ ** bundle. On the other hand, obviously we want to create a nice and
+ ** proper, FSH compliant application, which can be packaged and installed
+ ** in a modern Linux distribution as first class citizen. We can fulfil
+ ** both demands by establishing a convention how the application can
+ ** discover the very basic parts necessary to start up into the `main()`
+ ** function and read a setup configuration. This setup configuration
+ ** in turn supports the definition of _search paths_ -- which then
+ ** allows us to deliver the application in a bundle structure which
+ ** both can be run from a single root folder and likewise easily
+ ** be mapped into FSH compliant installation folders by the
+ ** packager.
+ ** 
+ ** @see lumiera::AppState::AppState()
+ ** @see main.cpp
+ ** 
+ */
+
+
 #ifndef COMMON_BASIC_SETUP_H
 #define COMMON_BASIC_SETUP_H
 

src/common/config-interface.c

@@ -21,6 +21,14 @@
 * *****************************************************/
 
 
+/** @file config-interface.c
+ ** A public interface to a (planned) global configuration system.
+ ** This is part of a drafted configuration system (2008).
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
+ */
+
+
 #include "common/config-interface.h"
 #include "common/config.h"
 

src/common/config-interface.h

@@ -28,6 +28,9 @@
  ** planned in 2008).
  ** 
  ** @note this is unfinished work, development in this area stalled in 2008
+ ** @warning since 2012 it is not clear if we retain this kind of configuration system.
+ ** @todo as of 2016, the code is still there in same unfinished shape and basically unused
+ ** 
  ** @see config.h
  */
 

src/common/config-lookup.c

@@ -22,7 +22,10 @@
 
 
 /** @file config-lookup.c
+ ** Implementation draft for a configuration system (2008).
  ** Implementation of the lookup of configuration keys
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
  */
 
 

src/common/config-lookup.h

@@ -21,6 +21,19 @@
 */
 
 
+/** @file config-lookup.h
+ ** Lookup of configuration keys in a low-level configuration system.
+ ** Configuration keys are dynamically stored in a splay tree.
+ ** This happens for defaults, loaded config files and entries which are set explicitly.
+ ** The system maintains no central registry of all possible keys.
+ ** We store here the full keys of config entries as well as the keys of section prefixes.
+ ** Section prefixes are stored with a trailing dot to disambiguate them from entry keys.
+ ** 
+ ** @warning since 2012 it is not clear if we retain this kind of configuration system.
+ ** @todo as of 2016, the code is still there but remains mostly unused
+ */
+
+
 #ifndef COMMON_CONFIG_LOOKUP_H
 #define COMMON_CONFIG_LOOKUP_H
 
@@ -37,22 +50,12 @@ typedef lumiera_config_lookupentry* LumieraConfigLookupentry;
 
 #include "common/configitem.h"
 
-
 #include <nobug.h>
 
 
-/**
- * @file
- * Lookup of configuration keys. Configuration keys are dynamically stored in a splay tree.
- * This happens for defaults, loaded config files and entries which are set explicitly.
- * The system maintains no central registry of all possible keys.
- * We store here the full keys of config entries as well as the keys of section prefixes.
- * Section prefixes are stored with a trailing dot to disambiguate them from entry keys.
- */
-
-
 LUMIERA_ERROR_DECLARE (CONFIG_LOOKUP);
 
+
 /**
  * Just contains a hashtable to give sufficient abstraction.
  */

src/common/config-rules.hpp

@@ -26,10 +26,10 @@
  ** By using the Query template, you can pose a query in prolog syntax and get some
  ** existing or newly created object fulfilling the requested predicates. The actual 
  ** implementation is hidden behind the #instance (Singleton factory). As of 1/2008, 
- ** it is \e planned to use an embedded YAP Prolog system at some point in the future,
+ ** it is _planned_ to use an embedded YAP Prolog system at some point in the future,
- ** for now we use a \link MockConfigRules mock implementation \endlink employing a
+ ** for now we use a [mock implementation](\ref MockConfigRules) based on lookup in
- ** preconfigured Map.
+ ** a hard-wired, preconfigured Map.
- **
+ ** 
  ** Fully implementing this facility would require the participating objects to register capabilities
  ** they want to provide, together with functors carrying out the necessary configuration steps.
  ** All details and consequences of this approach still have to be worked out...
@@ -47,13 +47,14 @@
  **
  ** @note this is rather a concept draft and left as such for now... don't take this code too literal!
  ** @todo clarify the relation of config query and query-for-defaults   ///////////////TICKET #705
+ ** @todo as of 11/2016 the situation is basically the same: this is placeholder code
+ **       and just implemented enough to keep us going without violating the architecture vision
  **
  ** @see lumiera::Query
  ** @see mobject::session::DefsManager
  ** @see asset::StructFactory 
  ** @see config-resolver.hpp specialised setup for the Proc-Layer
  ** @see fake-configrules.hpp currently used dummy-implementation
- ** @see 
  **
  */
 

src/common/config-typed.c

@@ -22,8 +22,11 @@
 
 
 /** @file config-type.d
- ** Implementation: high level typed configuration interfaces.
+ ** Implementation draft for a configuration system (2008).
+ ** This file implements high level typed configuration interfaces.
  ** @note unfinished draft from 2008
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
  */
 
 #include "include/logging.h"

src/common/config-wordlist.c

@@ -21,6 +21,15 @@
 * *****************************************************/
 
 
+/** @file config-wordlist.c
+ ** Draft for a configuration system (2008).
+ ** Part of this is the implementation of a word list with
+ ** search and access functions
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
+ */
+
+
 #include "include/logging.h"
 #include "lib/error.h"
 #include "lib/tmpbuf.h"

src/common/config.c

@@ -21,6 +21,13 @@
 * *****************************************************/
 
 
+/** @file config.c
+ ** Implementation of a draft for application configuration from 2008.
+ ** @warning since 2012 it is unclear if we retain this approach
+ ** @todo as of 2016 this code is not used and never was
+ */
+
+
 #include "include/logging.h"
 #include "lib/safeclib.h"
 #include "lib/tmpbuf.h"

src/common/config.h

@@ -33,6 +33,8 @@
  ** to revisit the topic when we've gained a better understanding of
  ** session storage and management of default values and user preferences.
  ** 
+ ** @todo as of 2016, this code is not in any meaningful use
+ ** 
  ** @see lumiera::BasicSetup simple start-up configuration
  ** @see http://lumiera.org/documentation/technical/backend/ConfigLoader.html ConfigLoader draft from 2008
  */

src/common/configentry.c

@@ -21,6 +21,13 @@
 * *****************************************************/
 
 
+/** @file configentry.c
+ ** Draft for a configuration system (2008).
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
+ */
+
+
 #include "lib/safeclib.h"
 #include "common/configentry.h"
 

src/common/configentry.h

@@ -21,6 +21,13 @@
 */
 
 
+/** @file configentry.h
+ ** Draft for a configuration system (2008).
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
+ */
+
+
 #ifndef COMMON_CONFIGENTRY_H
 #define COMMON_CONFIGENTRY_H
 

src/common/configfacade.cpp

@@ -21,6 +21,24 @@
 * *****************************************************/
 
 
+/** @file configfacade.cpp
+ ** Draft for a facade to access and retrieve configuration values
+ ** This was created as part of a first draft towards an application
+ ** wide configuration system. Later (around 2012) it became clear that
+ ** we can not judge the requirements for such a system yet, so we deferred
+ ** the topic altogether. Meanwhile, this facade is sporadically used to
+ ** mark the necessity to retrieve some "parametrisation values".
+ ** 
+ ** A preliminary implementation is backed by a `setup.ini` file,
+ ** located relative to the application binary.
+ ** 
+ ** @todo as of 2016, this seems not to be used much, if at all.
+ **       The GTK-UI, which in itself is very preliminary, retrieves
+ **       some values from configuration, most notably the name of
+ **       the GTK stylesheet (`gtk-lumiera.css` is the default)
+ */
+
+
 #include "include/logging.h"
 #include "include/lifecycle.h"
 #include "include/config-facade.h"

src/common/configitem.c

@@ -22,7 +22,10 @@
 
 
 /** @file configitem.c
- ** Implementation: create a configitem from a single line of the config file.
+ ** Implementation draft for a configuration system (2008).
+ ** Create a configitem from a single line of the config file.
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
  */
 
 

src/common/configitem.h

@@ -22,7 +22,11 @@
 
 
 /** @file configitem.h
- ** Hierarchy of configuration items.
+ ** Draft for a configuration system (2008).
+ ** @todo as of 2016 this code is unused and
+ **       likely to be replaced by a different approach.
+ ** 
+ ** # Hierarchy of configuration items.
  ** configitems form a 3 level hierarchy:
  ** 
  ** \verbatim

src/common/guifacade.cpp

@@ -21,6 +21,16 @@
 * *****************************************************/
 
 
+/** @file guifacade.cpp
+ ** Implementation of the GUI loader. Code generated from this
+ ** translation unit is linked into the core application, where it implements
+ ** the [Subsystem descriptor](subsys.hpp) for the _UI Subsystem._ When main()
+ ** activates and starts this subsystem, an instance of gui::GuiRunner will be
+ ** created, which causes the Lumiera UI plug-in to be loaded and a new thread
+ ** to be spawned, which launches the UI and performs the event loop.
+ */
+
+
 #include "gui/guifacade.hpp"
 #include "include/gui-notification-facade.h"
 #include "lib/sync.hpp"

src/common/interface-descriptor.h

@@ -21,6 +21,15 @@
 */
 
 
+/** @file interface-descriptor.h
+ ** A data record to describe interface, interface instances and plug-in
+ ** instances. It is used by the _interface system_ to register, open
+ ** and manage global extension points and separation interfaces between
+ ** the components of the application.
+ ** 
+ */
+
+
 #ifndef COMMON_INTERFACEDESCRIPTOR_H
 #define COMMON_INTERFACEDESCRIPTOR_H
 

src/common/interface.h

@@ -30,7 +30,7 @@
  ** versioned to provide forward and backward compatibility for both source and
  ** binary deployment of modules.
  **
- ** \par Overview
+ ** # Overview
  **
  ** To make an interface available to code so that the code can use the
  ** interface, the interface needs to be declared and then defined. We provide a
@@ -72,7 +72,7 @@
  **                 ) // Exporting from an interface
  ** \endcode
  **
- ** \par Naming and Versioning
+ ** # Naming and Versioning
  **
  ** Interfaces have unique names and a major and minor version. The name and the major version
  ** is used to construct a C identifier for the interface, the minor version is implicitly defined

src/common/interfaceproxy.cpp

@@ -21,6 +21,25 @@
 * *****************************************************/
 
 
+/** @file interfaceproxy.cpp
+ ** Implementation of C++ binding proxies on top of the (plain-C based)
+ ** interface system. This is an implementation facility within the application core,
+ ** which allows to embody just an ["interface instance handle"](\ref instancehandle.hpp),
+ ** in order to get RAII-style registration of interfaces and loading of plug-ins.
+ ** 
+ ** A *crucial requirement* for this approach to work is, that any relevant interface
+ ** to be bound and exposed as C++ object needs to set up a concrete specialisation of
+ ** lumiera::facade::Proxy to drive instantiation of the actual binding proxy.
+ ** The relevant specialisations _need to be included explicitly_ into this
+ ** compilation unit!
+ ** 
+ ** The result of this setup is that clients can just invoke `SomeInterface::facade()`
+ ** and thus call through proper C++ bindings with type safety and automatic
+ ** lifecycle management.
+ ** 
+ */
+
+
 #include "include/interfaceproxy.hpp"
 #include "common/instancehandle.hpp"
 #include "lib/error.hpp"

src/common/option.cpp

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file option.cpp
+ ** Implementation of commandline argument handling,
+ ** based on lib Boost »program options«
+ */
+
+
 #include "lib/error.hpp"
 #include "lib/util.hpp"
 #include "common/option.hpp"

src/common/option.hpp

@@ -21,6 +21,28 @@
 */
 
 
+/** @file option.hpp
+ ** front-end for handling the commandline arguments.
+ ** Lumiera uses the [Boost program options library] for commandline parsing
+ ** and handling of a `setup.ini` file. After checking the commandline arguments
+ ** syntactically, the internal options representation is passed to the various
+ ** [Subsystems](\ref subsys.hpp) of the application. This mechanism allows
+ ** individual subsystems to decide if they want and need to start up at all.
+ ** Obviously, starting a subsystem also pulls up its prerequisites.
+ ** 
+ ** The idea behind this structure is to allow operating the application in
+ ** various _alternative modes,_ like starting "headless" (without UI), script
+ ** driven or as node in a renderfarm network.
+ ** 
+ ** [Boost program options library] : http://www.boost.org/doc/libs/1_55_0/doc/html/program_options.html
+ ** 
+ ** @see basic-setup.hpp
+ ** @see lumiera::AppState
+ ** @see lumiera::Config
+ ** 
+ */
+
+
 #ifndef LUMIERA_OPTION_H
 #define LUMIERA_OPTION_H
 

src/common/query/config-rules.cpp

@@ -22,6 +22,12 @@
 * *****************************************************/
 
 
+/** @file config-rules.cpp
+ ** Implementation backend part for a configuration rules / query system.
+ ** @todo placeholder and mostly not implemented as of 11/2016
+ */
+
+
 #include "lib/error.hpp"
 #include "common/query.hpp"
 #include "common/config-rules.hpp"

src/common/query/defs-manager.hpp

@@ -21,6 +21,76 @@
 */
 
 
+/** @file defs-manager.hpp
+ ** Management of defaults and default rules.
+ ** It is one of the central ideas to shape the behaviour of Lumiera
+ ** not through hard wired procedures, but rather by the combination of
+ ** pattern elements driven by rules. A key element within this approach
+ ** is the notion of an *default*: Whenever some concrete calculation or
+ ** behaviour needs an additional element as missing link, in order to
+ ** reach its intrinsic goals, we (the developers) ask ourselves if the
+ ** for of this additional element can be derived from first principles
+ ** or if it is already determined by the input set driving the operation.
+ ** If this is _not_ the case (and the expectation is that most elements
+ ** are not fully determined), then we _query for an default._ This pattern
+ ** creates a lot of implicit extension points, which are safe to use, since
+ ** they are defined on a logical level. We ask for something to fulfil a
+ ** given contract.
+ ** 
+ ** Contrast this to a system, which just has arbitrarily built-in flexibility
+ ** by parametrisation variables: such systems are known to be brittle, since
+ ** the _parameter values_ are implicitly tied to the behaviour of the operation
+ ** through _shared knowledge_ of implementation details. It requires both
+ ** "Druid knowledge" and an overall focus on the implementation mechanics to
+ ** adjust such parameters. In this respect, a logical query for defaults is
+ ** quite different, insofar it forces the implementation to respect abstractions
+ ** on a very fine grained level, and it allows to express the actual defaults
+ ** by rules which talk the language of the usage context, not the implementation
+ ** context. The user shall be able to define generic (logical) rules how the
+ ** Session should behave for the given editing project. And by combination
+ ** with an additional set of logical consistency rules, a resolution engine
+ ** can figure out what would be the right _default element_ to use at a
+ ** given point in the implementation.
+ ** 
+ ** @note as of 2017, we are far from such a system, but it is of uttermost
+ **       importance that we build our implementations with this goal in mind
+ ** 
+ ** # Configuration Query Interface
+ ** The [Defaults Manager](\ref DefsManager) exposes an interface similar to
+ ** a database. The intended audience of this interface is the writer of
+ ** low-level implementation code. This facade interface is meant to create
+ ** a more familiar front-end to an essentially logic and rules driven
+ ** configuration system. And, as an additional benefit, it can be implemented
+ ** just by a glorified table lookup. Which indeed is what we do until the more
+ ** elaborate rules based system is in place.
+ ** 
+ ** An implementation process in need for some missing link typically knows the
+ ** _type of that missing element._ Which means, this type is possibly an abstract
+ ** type and defines the contract any solution has to fulfil. Thus, the usage context
+ ** can just demand "give me a suitable XYZ!". In practice, there are several flavours
+ ** to this interaction, each of which is expressed by a dedicated method on the
+ ** DefsManager facade interface:
+ ** - we can just *retrieve* a suitable solution element, no questions asked.
+ ** - we can *query* for a suitable solution, while limiting the search to what
+ **   is already known and defined. This entails the possibility that there is
+ **   no known solution yet.
+ ** - we can *demand to fabricate* a suitable solution element. Such a call might
+ **   still deliver something already fabricated, but the emphasis is on the
+ **   "make it so" demand.
+ ** - we can *provide and associate* a solution element we created ourselves,
+ **   to be available from now on, and associated with a given query. Even
+ **   this call implicates the necessity for the query to be fulfilled by
+ **   the given element, which, as a consequence includes the possibility
+ **   of failure.
+ ** - for sake of completeness, we can also require a specific element to
+ **   be purged from knowledge
+ ** 
+ ** @see DefsManager_test
+ ** @see DefsManagerImpl_test
+ ** 
+ */
+
+
 #ifndef LUMIERA_QUERY_DEFS_MANAGER_H
 #define LUMIERA_QUERY_DEFS_MANAGER_H
 

src/common/query/defs-registry.hpp

@@ -31,7 +31,7 @@
  ** Basically, this piece of code defines a specialised index / storage table to hold
  ** Queries-for-default objects. This allows to remember what actually was used as
  ** "default" solution for some query and to oder possible default solutions.
- ** @remarks as of 2012, we're still using a fake implementation of the resolution,
+ ** @remarks as of 2017, we're still using a fake implementation of the resolution,
  **          no real resolution engine. While the basic idea of this "defaults registry"
  **          is likely to stay, the actual order relation and maybe even the components
  **          to be stored in this registry might be subject to change. 

src/common/query/query-resolver.cpp

@@ -21,6 +21,18 @@
 * *****************************************************/
 
 
+/** @file query-resolver.cpp
+ ** implementation of a framework to query and discover elements
+ ** based on logical rules. This framework builds on the notion of
+ ** possibly having several QueryResolver facilities to handle various
+ ** kinds of queries in an uniform way. To reflect that design, the
+ ** implementation is built round a DispatcherTable to forward requests
+ ** to concrete entities implementing the QueryResolver interface. The
+ ** actual query resolution mechanism is thus not part of the framework.
+ ** 
+ */
+
+
 #include "lib/multifact.hpp"
 #include "common/query/query-resolver.hpp"
 
@@ -97,7 +109,7 @@ namespace lumiera {
     REQUIRE (!dispatcher_->empty(), "attempt to issue a query without having installed any resolver (yet)");  
     
     if (!canHandle (query))
-      throw lumiera::error::Invalid ("unable to resolve this kind of query"); ////TICKET #197
+      throw lumiera::error::Invalid ("unable to resolve this kind of query"); //////////////////////////////////TICKET #197
     
     return dispatcher_->handle(query);
   }

src/common/query/query-resolver.hpp

@@ -21,6 +21,17 @@
 */
 
 
+/** @file query-resolver.hpp
+ ** framework and to resolve logical queries.
+ ** This header defines a family of interfaces and classes
+ ** to integrate resolution of logical, rules based queries into generic
+ ** implementation code. The concrete facility actually to resolve such queries
+ ** is abstracted away as QueryResolver. A prominent usage example is the session,
+ ** which allows to query for elements "somewhere within the model"
+ ** 
+ */
+
+
 #ifndef LUMIERA_QUERY_RESOLVER_H
 #define LUMIERA_QUERY_RESOLVER_H
 

src/common/subsys.cpp

@@ -21,6 +21,19 @@
 * *****************************************************/
 
 
+/** @file subsys.cpp
+ ** Implementation details of a »subsystem descriptor«.
+ ** The application is split into various such subsystems,
+ ** which are prompted by main() to start/stop.
+ ** 
+ ** @see subsystem-runner.hpp
+ ** @see lumiera::AppState
+ ** @see facade.cpp
+ ** @see main.cpp
+ ** 
+ */
+
+
 #include "common/subsys.hpp"
 
 

src/common/subsystem-runner.hpp

@@ -21,6 +21,28 @@
 */
 
 
+/** @file subsystem-runner.hpp
+ ** Manage execution of the independend [Subsystems](\ref subsys.hpp)
+ ** of the Lumiera application. The SubsystemRunner is used by
+ ** lumiera::AppState::init() for actually "performing" the various subsystems,
+ ** as defined by their [Subsystem descriptors](\ref lumiera::Subsys). Together
+ ** these parts define the lifecycle protocol.
+ ** 
+ ** @remark While this facility is still pretty much the first implementation draft
+ **         from 2008, it fulfilled our needs to express simple dependencies and to
+ **         conduct a controlled shutdown in case of fatal problems. The operations
+ **         protocol implied by this implementation might be somewhat brittle and
+ **         creates strong ties to implementation details, like the fine points
+ **         of thread handling and locking. If we ever consider to build an
+ **         improved subsystem runner, we should care to include the
+ **         full set of lifecycle callbacks, similar to a
+ **         two phase commit in databases.
+ ** 
+ ** @see SubsystemRunner_test
+ ** 
+ */
+
+
 #ifndef LUMIERA_SUBSYSTEMRUNNER_H
 #define LUMIERA_SUBSYSTEMRUNNER_H
 

src/gui/ctrl/playback-controller.cpp

@@ -21,6 +21,14 @@
 * *****************************************************/
 
 
+/** @file playback-controller.cpp
+ ** Implementation parts of PlaybackController.
+ ** @warning this is preliminary code and will be reworked, once
+ **          we're able to connect to actual playback processes
+ **          performed by the render engine.
+ */
+
+
 #include "gui/ctrl/playback-controller.hpp"
 #include "gui/display-service.hpp"
 #include "lib/error.hpp"

src/gui/dialog/dialog.hpp

@@ -21,6 +21,11 @@
 */
 
 
+/** @file dialog.hpp
+ ** Global constants and definitions for dialogs.
+ */
+
+
 #ifndef GUI_DIALOG_DIALOG_H
 #define GUI_DIALOG_DIALOG_H
 

src/gui/dialog/name-chooser.cpp

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file name-chooser.cpp
+ ** Implementation details of NameChooser,
+ ** a dialog to enter a name string.
+ */
+
+
 #include "gui/gtk-lumiera.hpp"
 #include "gui/dialog/name-chooser.hpp"
 #include "gui/dialog/dialog.hpp"

src/gui/dialog/name-chooser.hpp

@@ -21,6 +21,11 @@
 */
 
 
+/** @file name-chooser.hpp
+ ** Dialog to enter a string name.
+ */
+
+
 #ifndef GUI_DIALOG_NAME_CHOOSER_H
 #define GUI_DIALOG_NAME_CHOOSER_H
 

src/gui/dialog/preferences-dialog.hpp

@@ -21,6 +21,14 @@
 */
 
 
+/** @file preferences-dialog.hpp
+ ** Dialog to manage application preferences.
+ ** @todo as of 2016, this is more of a place-holder, since we also
+ **       do not have decided on the implementation approach for
+ **       application preferences in general.
+ */
+
+
 #ifndef GUI_DIALOG_PREFERENCES_DIALOG_H
 #define GUI_DIALOG_PREFERENCES_DIALOG_H
 

src/gui/dialog/render.cpp

@@ -21,6 +21,12 @@
 * *****************************************************/
 
 
+/** @file render.cpp
+ ** Implementation of gui:dialog::Render, which is a Dialog
+ ** to set up a renter process and define output name and format.
+ */
+
+
 #include "gui/gtk-lumiera.hpp"
 
 #include "gui/dialog/render.hpp"

src/gui/dialog/render.hpp

@@ -21,7 +21,7 @@
 */
 
 /** @file render.hpp
- ** definition of the render output dialog
+ ** Dialog to set up a renter process and define output name and format.
  **
  */
 

src/gui/display-interface-proxy.hpp

@@ -40,6 +40,7 @@
 /* ==================== gui::Display ====================================== */
 
 #include "include/display-facade.h"
+#include "include/interfaceproxy.hpp"
 
 namespace lumiera {
   

src/gui/display-service.cpp

@@ -21,6 +21,13 @@
 * *****************************************************/
 
 
+/** @file display-service.cpp
+ ** Implementation of _Displayer Service,_ exposed as a public interface.
+ ** This service allows to set up _display slots,_ which can be handed over
+ ** to client code in the course of the play process for outputting frames.
+ */
+
+
 #include "gui/display-service.hpp"
 
 extern "C" {

src/gui/display-service.hpp

@@ -116,7 +116,7 @@ namespace gui {
    * the Lumiera Interface/Plugin system and creates
    * a forwarding proxy within the application core to
    * route calls through this interface.
-   * \par
+   * 
    * In addition to the Display interface, this class 
    * implements an additional service for the GUI, 
    * allowing actually to set up display slots, which

src/gui/gtk-lumiera.cpp

@@ -21,6 +21,10 @@
 * *****************************************************/
 
 
+/** @file gtk-lumiera.cpp
+ */
+
+
 #include "gui/gtk-lumiera.hpp"
 #include "gui/ctrl/ui-manager.hpp"
 #include "gui/ui-bus.hpp"

src/gui/guifacade.hpp

@@ -25,7 +25,7 @@
  ** lower layers of Lumiera. While part of the public interface of the Lumiera GUI,
  ** the implementation of this facility is part of the core application (and not
  ** contained within the GUI dynamic module), because it's job is to load and
- ** activate this module and to startup the GUI.
+ ** activate this module as plug-in and to startup the GUI.
  **
  ** @see lumiera::AppState
  ** @see lumiera::Option

src/gui/model/clip-track.cpp

@@ -20,6 +20,13 @@
 
 * *****************************************************/
 
+
+/** @file clip-track.cpp
+ ** Preliminary UI-model: Implementation of timeline track model object.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ */
+
 #include "clip-track.hpp"
 
 #include "clip.hpp"

src/gui/model/clip-track.hpp

@@ -21,9 +21,10 @@
 */
 
 /**
- * @file model/clip-track.hpp
+ ** @file model/clip-track.hpp
- * This file contains the definition of timeline track objects which
+ ** Preliminary UI-model: Definition of timeline track objects which contain clips.
- * contain clips.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
  */
 
 

src/gui/model/clip.cpp

@@ -21,6 +21,14 @@
 * *****************************************************/
 
 
+/** @file clip.cpp
+ ** Preliminary UI-model: implementation of a Clip object as placeholder to
+ ** base the GUI implementation on.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ */
+
+
 #include "gui/model/clip.hpp"
 #include "lib/time/mutation.hpp"
 

src/gui/model/clip.hpp

@@ -21,8 +21,10 @@
 */
 
 /** @file model/clip.hpp
- ** This file defines a Proxy Clip object to base the GUI implementation on.
+ ** Preliminary UI-model: a Proxy Clip object to base the GUI implementation on.
  ** Later this Clip object will be connected to the underlying model in Proc-Layer.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
  */
 
 #ifndef GUI_MODEL_CLIP_H

src/gui/model/group-track.cpp

@@ -20,6 +20,14 @@
 
 * *****************************************************/
 
+
+/** @file group-track.cpp
+ ** Preliminary UI-model: Implementation for the group track timeline objects.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** @deprecated the existing timeline implementation will be completely rewritten
+ */
+
 #include "group-track.hpp"
 
 namespace gui {

src/gui/model/group-track.hpp

@@ -21,7 +21,10 @@
 */
 
 /** @file widget/timeline/group-track.hpp
- ** This file contains the definition of group track timeline objects
+ ** Preliminary UI-model: Definition of group track timeline objects.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** @deprecated the existing timeline implementation will be completely rewritten
  */
 
 
@@ -36,6 +39,7 @@ namespace model {
 
 /**
  * A class representation of a grouping of tracks.
+ * @deprecated the existing timeline implementation will be rewritten
  */
 class GroupTrack : public ParentTrack
 {

src/gui/model/parent-track.cpp

@@ -20,6 +20,14 @@
 
 * *****************************************************/
 
+
+/** @file parent-track.cpp
+ ** Preliminary UI-model: Implementation of ParentTrack.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** @deprecated the existing timeline implementation will be completely rewritten
+ */
+
 #include "parent-track.hpp"
 #include <boost/foreach.hpp>
 

src/gui/model/parent-track.hpp

@@ -20,9 +20,12 @@
 
 */
 /** @file parent-track.hpp
- ** This file contains the definition of ParentTrack, a class which
+ ** Preliminary UI-model: Definition of ParentTrack, a class which
  ** represents a base functionality for tracks and sequences which
- ** are also track parents. This class wraps proc layer data
+ ** are also track parents. This class was intended to wraps proc layer data.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** @deprecated the existing timeline implementation will be completely rewritten
  */
 
 #ifndef PARENT_TRACK_HPP
@@ -35,8 +38,8 @@ namespace gui {
 namespace model {
 
 /**
- * ParentTrack is the abstract base class of all tracks that can parent
+ * ParentTrack is the abstract base class of all tracks that can parent children.
- * children.
+ * @deprecated the existing timeline implementation will be rewritten
  */
 class ParentTrack :
   public Track,

src/gui/model/project.cpp

@@ -21,6 +21,15 @@
 * *****************************************************/
 
 
+/** @file project.cpp
+ ** Preliminary UI-model: Implementation of Project, a class which
+ ** stores project data, and wraps proc layer data.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** 
+ */
+
+
 #include "gui/model/project.hpp"
 #include "gui/model/sequence.hpp"
 

src/gui/model/project.hpp

@@ -21,8 +21,10 @@
 */
 
 /** @file project.hpp
- ** This file contains the definition of Project, a class which
+ ** Preliminary UI-model: Definition of Project, a class which
  ** stores project data, and wraps proc layer data.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
  ** 
  ** @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

src/gui/model/sequence.cpp

@@ -20,6 +20,13 @@
 
 * *****************************************************/
 
+
+/** @file sequence.cpp
+ ** Preliminary UI-model: implementation of an editable sequence.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ */
+
 #include "gui/model/sequence.hpp"
 #include "include/logging.h"
 

src/gui/model/sequence.hpp

@@ -21,10 +21,12 @@
 */
 
 /** @file sequence.hpp
- ** The GUI-Model representation of an editable sequence.
+ ** Preliminary UI-model: representation of an editable sequence.
- ** @todo Currently (1/2014) this is a dummy placeholder, but later on
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
- **       the GUI-Model entities will be connected to the Session model
+ **          and will be replaced in entirety by UI-Bus and diff framework.
- **       through the use of PlacementRef
+ ** 
+ ** @todo Currently (1/2014) this is a dummy placeholder, intention is
+ **       to connect GUI-Model entities to the Session model eventually.
  */
 
 

src/gui/model/track.cpp

@@ -21,6 +21,14 @@
 * *****************************************************/
 
 
+/** @file track.cpp
+ ** Preliminary UI-model: Implementation for the track timeline objects.
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** @deprecated the existing timeline implementation will be completely rewritten
+ */
+
+
 #include "gui/model/track.hpp"
 #include "gui/model/parent-track.hpp"
 

src/gui/model/track.hpp

@@ -20,8 +20,11 @@
 
 */
 /** @file track.hpp
- ** This file contains the definition of Track, a class which
+ ** Preliminary UI-model: Definition of Track, a class which
  ** represents a track, and wraps proc layer data
+ ** @warning as of 2016 this UI model is known to be a temporary workaround
+ **          and will be replaced in entirety by UI-Bus and diff framework.
+ ** @deprecated the existing timeline implementation will be completely rewritten
  */
 
 

src/gui/notification-interface-proxy.hpp

@@ -37,8 +37,9 @@
 
 
 /* ==================== GuiNotification =================================== */
-
+    
 #include "include/gui-notification-facade.h"
+#include "include/interfaceproxy.hpp"
 
 namespace gui {
   

src/gui/notification-service.cpp

@@ -29,6 +29,11 @@
  ** 
  */
 
+/** @file notification-service.cpp
+ ** @todo write documentation for the notification service
+ */
+
+
 #include "gui/notification-service.hpp"
 #include "include/logging.h"
 #include "lib/depend.hpp"

src/gui/output/displayer.cpp

@@ -23,6 +23,18 @@
 * *****************************************************/
 
 
+/** @file displayer.cpp
+ ** Implementation of a displayer object, intended for creating
+ ** a video display in the UI. This class was created as part of
+ ** an initial draft of the user interface.
+ ** @warning as of 2016 it is not clear, if this code will be
+ **          evolved into the actual display facility, or be
+ **          replaced and rewritten, when we're about to 
+ **          create a functional video display connected
+ **          to the render engine. 
+ */
+
+
 #include "gui/gtk-lumiera.hpp"
 #include "gui/output/displayer.hpp"
 #include "gui/output/xvdisplayer.hpp"

src/gui/output/displayer.hpp

@@ -24,7 +24,11 @@
 
 /** @file displayer.hpp
  ** The Displayer serves as base of all video display implementations
- ** 
+ ** @warning as of 2016 it is not clear, if this code will be
+ **          evolved into the actual display facility, or be
+ **          replaced and rewritten, when we're about to 
+ **          create a functional video display connected
+ **          to the render engine. 
  */
 
 

src/gui/output/gdkdisplayer.cpp

@@ -23,6 +23,13 @@
 * *****************************************************/
 
 
+/** @file gdkdisplayer.cpp
+ ** Dysfunctional implementation code, formerly used to
+ ** create a video display based on GDK
+ ** @deprecated obsolete since GTK-3
+ */
+
+
 #include "gui/gtk-lumiera.hpp"
 #include "gui/output/gdkdisplayer.hpp"
 

src/gui/output/xvdisplayer.cpp

@@ -23,6 +23,16 @@
 * *****************************************************/
 
 
+/** @file xvdisplayer.cpp
+ ** Implementation of video output via XVideo
+ ** @warning as of 2016 it is not clear, if this code will be
+ **          evolved into the actual display facility, or be
+ **          replaced and rewritten, when we're about to 
+ **          create a functional video display connected
+ **          to the render engine. 
+ */
+
+
 #include "gui/gtk-lumiera.hpp"
 #include "gui/output/xvdisplayer.hpp"
 #include "include/logging.h"