Doxygen: fill in file level headlines for further application core services

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>
@@ -22,7 +22,13 @@
 
 
 /** @file appstate.cpp
- ** TODO 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
  */
 
 

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

@@ -22,7 +22,14 @@
 
 
 /** @file basic-setup.cpp
- ** TODO 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
  */
 
 

src/common/basic-setup.hpp

@@ -22,7 +22,31 @@
 
 
 /** @file basic-setup.hpp
- ** TODO 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
+ ** 
  */
 
 

src/common/interface-descriptor.h

@@ -22,7 +22,11 @@
 
 
 /** @file interface-descriptor.h
- ** TODO 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.
+ ** 
  */
 
 

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

@@ -22,7 +22,21 @@
 
 
 /** @file interfaceproxy.cpp
- ** TODO 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.
+ ** 
  */
 
 

src/common/option.cpp

@@ -22,7 +22,8 @@
 
 
 /** @file option.cpp
- ** TODO option.cpp
+ ** Implementation of commandline argument handling,
+ ** based on lib Boost »program options«
  */
 
 

src/common/option.hpp

@@ -22,7 +22,24 @@
 
 
 /** @file option.hpp
- ** TODO 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
+ ** 
  */
 
 

src/common/subsys.cpp

@@ -22,7 +22,15 @@
 
 
 /** @file subsys.cpp
- ** TODO 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
+ ** 
  */
 
 

src/common/subsystem-runner.hpp

@@ -22,7 +22,24 @@
 
 
 /** @file subsystem-runner.hpp
- ** TODO 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
+ ** 
  */
 
 

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/notification-interface-proxy.hpp

@@ -39,6 +39,7 @@
 /* ==================== GuiNotification =================================== */
     
 #include "include/guinotification-facade.h"
+#include "include/interfaceproxy.hpp"
 
 namespace gui {
   

src/include/interfaceproxy.hpp

@@ -22,7 +22,7 @@
 
 /** @file interfaceproxy.hpp
  ** Facade Interfaces Lifecycle. Communication between the Layers within Lumiera
- ** usually is routed through <b>Layer Separation Interfaces</b>. These are comprised
+ ** usually is routed through *Layer Separation Interfaces*. These are comprised
  ** of a Facade interface and a equivalent rendering as C Language interface defined
  ** with the help of the Interface/Plugin system. But in order to be able to actually
  ** access a service via this Facade, you need an instance of the interface.
@@ -33,12 +33,12 @@
  ** Typically there is another subclass of the Facade interfaces sitting "on the other side"
  ** of the interface barrier and actually implementing the functionality. The template
  ** facade::Accessor can be thought of as a factory creating such a proxy instance of the
- ** facade interface for the client code to use. Typically, an instance of the \em factory
+ ** facade interface for the client code to use. Typically, an instance of the _factory_
  ** is embedded (as a static functor member object) right within the otherwise abstract 
- ** facade interface, this way allowing the client code to write e.g. \c XYZInterface::facade()
- ** to yield a reference to a proxy object implementing \c XYZInterface.
+ ** facade interface, this way allowing the client code to write e.g. `XYZInterface::facade()`
+ ** to yield a reference to a proxy object implementing `XYZInterface`.
  ** 
- ** Interface Lifecycle
+ ** # Interface Lifecycle
  ** 
  ** Instances of an Interface are either directly provided by some facility within the core,
  ** or they are loaded from a shared module (plugin). In either case this means the interface
@@ -63,8 +63,8 @@
  ** While client code just includes the interface header (including interfaceproxy.hpp
  ** in turn), there needs to be an actual implementation of each proxy object located in
  ** some translation unit. The usual place is interfaceproxy.cpp, which gets linked into 
- ** \c liblumieracommon.so and contains actual specialisations and literal forwarding
- ** code <i>for each individual facade.</i>
+ ** `liblumieracommon.so` and contains actual specialisations and literal forwarding
+ ** code _for each individual facade._
  **
  ** @see interface.h
  ** @see plugin.h

src/proc/play/dummy-player-interface-proxy.hpp

@@ -54,6 +54,7 @@
     
 //#include "proc/play/dummy-player-service.hpp"
 #include "include/dummy-player-facade.h"
+#include "include/interfaceproxy.hpp"
 
 namespace lumiera {