Doxygen Fixes (#1062)

This changeset fixes a huge pile of problems, as indicated in the
error log of the Doxygen run after merging all the recent Doxygen improvements

unfortunately, auto-linking does still not work at various places.
There is no clear indication what might be the problem.
Possibly the rather unstable Sqlite support in this Doxygen version
is the cause. Anyway, needs to be investigated further.

doc/devel/Doxyfile

@@ -50,7 +50,7 @@ TYPEDEF_HIDES_STRUCT   = YES
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 EXTRACT_PRIVATE        = YES
 EXTRACT_PACKAGE        = NO
 EXTRACT_STATIC         = YES
@@ -204,7 +204,7 @@ EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
 INCLUDE_PATH           =
 INCLUDE_FILE_PATTERNS  =
-PREDEFINED             =
+PREDEFINED             = __cplusplus
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------

src/backend/filehandlecache.h

@@ -89,7 +89,6 @@ lumiera_filehandlecache_checkout (LumieraFilehandle handle);
 /**
  * Put a filehandle into the cache
  * Filehandles which are checked in are subject of cache aging and might get destroyed and reused.
- * @param self the filehandlecache
  * @param handle the filehandle to be checked in
  */
 void

src/backend/fileheader.h

@@ -146,7 +146,7 @@ lumiera_fileheader_create (LumieraFile file, char* fourcc, int version, size_t s
  * @param fourcc pointer to a string of length 4 with the expected identifier for the file
  * @param size The actual size of all header data, including following format specific data
  * @param flags_expected expect this flags being set
- * @param flags_remov remove this flags when opening
+ * @param flags_remove remove this flags when opening
  * @return A lumiera_fileheader object by value, .header and .map are set to NULL on error.
  */
 lumiera_fileheader

src/common/advice/binding.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file binding.cpp
+/** @file advice/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

src/common/advice/index.hpp

@@ -51,22 +51,22 @@
  ** coded explicitly as ProvisionCluster and RequestCluster -- both based on a vector of entries.
  ** In case of the provisions, there is a stack-like order, inasmuch additions happen at the back
  ** and solutions are always searched starting from the end. Because of the basic structure of
- ** a binding match, solutions are possible \only between provision/request - clusters with the
+ ** a binding match, solutions are possible _only_ between provision/request - clusters with the
  ** same hash value (which is based on the predicate symbols within the patterns to match). Thus,
  ** in case of changing an existing request or solution, the internal handling is different,
  ** depending on the new value to belong or don't belong to the same cluster (hash code).
  ** It's possible (for patterns including variables) that an entry leading to a solution with
  ** the old provision doesn't match a new provision (and vice versa); thus we'll have to traverse
  ** the contents of the whole cluster, find all old solutions, match against the new counterpart
- ** and treating those entries \em not matching with the new value as if they where completely
+ ** and treating those entries _not matching_ with the new value as if they where completely
  ** newly added entries. In case we don't find any solution, the entries are supposed to be
  ** implemented such as to fall back to an default solution automatically (when receiving
- ** a \c NULL solution)
+ ** a `NULL` solution)
  ** 
  ** @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
  **       later at various places within proc-layer.
- ** @note for now, \em only the case of a completely constant (ground) pattern is implemented.
+ ** @note for now, _only_ the case of a completely constant (ground) pattern is implemented.
  **       Later we may consider to extend the binding patterns to allow variables. The mechanics
  **       of the index are designed right from start to support this case (and indeed the index
  **       could be much simpler if it wasn't to deal with this foreseeable additional complexity:

src/common/config-rules.hpp

@@ -25,9 +25,9 @@
  ** Interface for accessing rule based configuration.
  ** 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, 
+ ** implementation will be hidden behind a `instance` (Singleton factory). As of 1/2008,
  ** it is _planned_ to use an embedded YAP Prolog system at some point in the future,
- ** for now we use a [mock implementation](\ref MockConfigRules) based on lookup in
+ ** for now we use a [mock implementation](\ref fake-configrules.hpp) based on lookup in
  ** a hard-wired, preconfigured Map.
  ** 
  ** Fully implementing this facility would require the participating objects to register capabilities
@@ -37,7 +37,7 @@
  ** \par relation to Query and QueryResolver
  ** The ConfigRules resolver is just a special kind of QueryResolver, able to handle specific kinds
  ** of queries. Clients using the ConfigRules directly get a more easy to use point-and-shot style
- ** interface, allowing just to retrieve some \em suitable solution, instead of having to iterate
+ ** interface, allowing just to retrieve some _suitable solution_, instead of having to iterate
  ** through a result set.
  ** 
  ** @todo right now (12/2012) the above paragraph is a lie.

src/common/config-typed.c

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file config-type.d
+/** @file config-type.c
  ** Implementation draft for a configuration system (2008).
  ** This file implements high level typed configuration interfaces.
  ** @note unfinished draft from 2008

src/common/integration/common-services.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file common-serivces.cpp 
+/** @file common-services.cpp
  ** Wire library facilities directly into application core services 
  ** This translation unit serves to complete the definition of some parts of the Lumiera library.
  ** While library facilities usually are written to be self-contained, at places we want "magic"

src/common/query/defs-manager.hpp

@@ -56,9 +56,9 @@
  **       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
+ ** The [Defaults Manager](\ref lumiera::query::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

src/common/query/query-resolver.hpp

@@ -97,7 +97,7 @@ namespace lumiera {
   /**
    * Interface: a facility for resolving (some kind of) queries
    * A concrete subclass has the ability to create Resolution instances
-   * in response to specific queries of some kind, \link #canHandle if applicable \endlink.
+   * in response to specific queries of some kind, [if applicable](QueryResolver::canHandle).
    * Every resolution mechanism is expected to enrol by calling #installResolutionCase.
    * Such a registration is considered permanent; a factory function gets stored,
    * assuming that the entity to implement this function remains available
@@ -158,7 +158,7 @@ namespace lumiera {
   
   
   /** notational convenience shortcut,
-   *  synonymous to #resolveBy */
+   *  synonymous to Query<RES>::resolveBy() */
   template<typename RES>
   inline typename Query<RES>::iterator
   Query<RES>::operator() (QueryResolver const& resolver)  const

src/common/subsys.hpp

@@ -102,10 +102,10 @@ namespace lumiera {
        *  When this subsystem ceases to work, it must ensure to activate
        *  the given callback signal.
        *  @param options may be influencing the operation mode 
-       *  @param termination to be signalled by the subsystem.
+       *  @param SigTerm to be signalled by the subsystem.
        *  @warning termination must be signalled reliably.  
-       *  @return \c true if actually started. */
-      virtual bool start (lumiera::Option&, SigTerm)  =0;
+       *  @return `true` if actually started. */
+      virtual bool start (lumiera::Option& options, SigTerm)  =0;
       
       
       /** initiate termination of this subsystem.

src/gui/ctrl/bus-term.hpp

@@ -32,9 +32,9 @@
  ** \par Lifecycle and identity
  ** An BusTerm is always created starting from another BusTerm, to
  ** which it will be wired. Moreover, each BusTerm bears a distinct
- ** [identity](\ref ::endpointID_), which is used as _implicit subject_
+ ** [identity](\ref BusTerm::endpointID_), which is used as _implicit subject_
  ** for emanating messages, or as explicit destination for routing.
- ** The whole [UI-Bus](\ref ui-bus.hpp) is built to perform within the
+ ** The whole [UI-Bus](ui-bus.hpp) is built to perform within the
  ** UI event thread and thus is _not threadsafe_. For that reason,
  ** the automatic detachment built into each BusTerm's dtor is
  ** sufficient to ensure sane connectivity.

src/gui/ctrl/core-service.hpp

@@ -35,9 +35,9 @@
  ** CoreService is a PImpl to manage all the technical parts of actual
  ** service provision. When it goes down, all services are decommissioned.
  ** A part of these lifecycle technicalities is to manage the setup of the
- ** [UI-Bus main hub](\ref ctrl::Nexus), which requires some trickery, since
- ** both CoreService and Nexus are mutually interdependent from an operational
- ** perspective, since they exchange messages in both directions.
+ ** [UI-Bus main hub](\ref gui::ctrl::Nexus), which requires some trickery,
+ ** since both CoreService and Nexus are mutually interdependent from an
+ ** operational perspective, since they exchange messages in both directions.
  ** 
  ** ## Bus connection and topology
  ** The CoreService plays a central role within the UI, since it represents

src/gui/ctrl/mutation-message.hpp

@@ -22,7 +22,7 @@
 
 
 /** @file mutation-message.hpp
- ** Message on the UI-Bus to cause changes on the targeted [UI-Element](\ref Tangible).
+ ** Message on the UI-Bus to cause changes on the targeted [UI-Element](\ref model::Tangible).
  ** The UI-Bus offers a dedicated API to direct MutationMessages towards Tangible elements,
  ** as designated by the given ID. Actually, such messages serve as capsule to transport a
  ** diff-sequence -- since a diff sequence as such is always concrete and tied to a specific context,

src/gui/ctrl/playback-controller.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file controller/playback-controller.hpp
+/** @file playback-controller.hpp
  ** This file contains the definition of the playback controller object.
  ** 
  ** @deprecated this represents an early design of playback and will be reworked

src/gui/guistart.cpp

@@ -36,7 +36,7 @@
  ** body, while the interface is opened via an InstanceHandle member. The `launchUI()` call
  ** starts a new thread, which then becomes the UI event thread and remains blocked within
  ** the main GTK event loop. Before entering this loop, the CoreService of the GUI and
- ** especially the [UI-Bus](\ref ui-bus.hpp) is started see \ref GtkLumiera::run.
+ ** especially the [UI-Bus](\ref ui-bus.hpp) is started see \ref GtkLumiera::main().
  ** This entails also to open the primary "business" interface(s) of the GUI
  ** (currently as of 1/16 this is the interface gui::GuiNotification.)
  ** 

src/gui/interact/interaction-director.hpp

@@ -24,7 +24,7 @@
 /** @file interaction-director.hpp
  ** The top-level controller to connect model and user interaction state.
  ** Within the Lumiera UI, relevant entities from the session model are mapped onto and represented
- ** by corresponding [UI-Elements](\ref model::Tangible). Consequently, there is a hierarchy of
+ ** by corresponding [UI-Elements](\ref Tangible). Consequently, there is a hierarchy of
  ** interrelated UI elements mirroring the hierarchy within the session model. And, while in the
  ** latter, there is a _conceptual root node_ to correspond to the session itself, within the UI
  ** there is a top-level controller to mirror and represent that root element: The InteractionDirector.

src/gui/model/clip.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file clip.cpp
+/** @file gui/model/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

src/gui/model/clip.hpp

@@ -20,7 +20,7 @@
 
 */
 
-/** @file model/clip.hpp
+/** @file gui/model/clip.hpp
  ** 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

src/gui/model/diagnostics.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file diagnostics.hpp
+/** @file gui/model/diagnostics.hpp
  ** Service for diagnostics.
  ** This header defines the basics of...
  ** 

src/gui/model/group-track.hpp

@@ -20,7 +20,7 @@
 
 */
 
-/** @file widget/timeline/group-track.hpp
+/** @file gui/model/group-track.hpp
  ** 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.

src/gui/model/sequence.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file sequence.cpp
+/** @file gui/model/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.

src/gui/model/sequence.hpp

@@ -20,7 +20,7 @@
 
 */
 
-/** @file sequence.hpp
+/** @file gui/model/sequence.hpp
  ** Preliminary UI-model: representation 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.

src/gui/model/tangible.hpp

@@ -26,7 +26,8 @@
  ** This is a generic foundation for any elements of more than local relevance
  ** within the Lumiera UI.<br/> Any such element is connected to the [UI-Bus](ui-bus.hpp).
  ** 
- ** \par rationale
+ ** ## rationale
+ ** 
  ** Simple user interfaces can be built by wiring up the actions right within the
  ** code processing the trigger of actions. This leads to core functionality littered
  ** and tangled with presentation code. The next step towards a more sane architecture
@@ -52,7 +53,8 @@
  ** `Tangible::uiBus_`
  ** can be used for interaction with core services.
  ** 
- ** \par the generic interface element API
+ ** ## the generic interface element API
+ ** 
  ** The _generic interface element_ based on [Tangible](\ref model::Tangible) covers a set of behaviour
  ** common to  all elements of the interface. This behaviour is targeted towards the _integration_
  ** with the core application. Beyond that, there are still several concerns regarding presentation,
@@ -96,7 +98,8 @@
  ** These are sent as notifications just to some relevant top level element, expecting this element
  ** to request a [diff](tree-diff.hpp) and to mutate contents into shape recursively.
  ** 
- ** \par Interactions
+ ** ## Interactions
+ ** 
  ** - **lifecycle**: connect to an existing term, supply the [EntryID](\ref Tangible::ID) of the new element.
  **   This interaction also implies, that the element automatically detaches itself at end of life.
  ** - **act**: send a \ref GenNode representing the action

src/gui/panel/assets-panel.hpp

@@ -47,8 +47,8 @@ namespace panel{
     {
     public:
       /** Build a new Asset-Panel
-       * @param panel_manager The owner panel manager widget.
-       * @param dock_item The GdlDockItem that will host this panel.
+       * @param PanelManager The owner panel manager widget.
+       * @param DockItem The GdlDockItem that will host this panel.
        */
       AssetsPanel (workspace::PanelManager&, Gdl::DockItem&);
       

src/gui/timeline/clip-widget.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file v.cpp
+/** @file clip-widget.cpp
  ** Implementation details of _clip display_ within the Lumiera UI.
  ** 
  ** @note a "clip" can be a media clip proper, or just some part

src/gui/timeline/header-pane-widget.hpp

@@ -23,12 +23,12 @@
 
 /** @file header-pane-widget.hpp
  ** Widget to show an always visible track header area within the timeline UI.
- ** [The fork](\ref session::Fork), a recursively nested system of scopes, is rendered within
+ ** [The fork](\ref Fork), a recursively nested system of scopes, is rendered within
  ** the timeline display as a system of nested tracks. Each of these tracks possibly holds some
  ** child tracks plus some actual media clips, which all inherit parameters of placement from
  ** this fork ("track"). These parameters address various aspects of how content is attached
  ** ("placed") into the model at large. So, for each track, we create a
- ** ["patchbay" area](\ref timeline::PatchbayWidget) to manage those placement parameters.
+ ** ["patchbay" area](\ref PatchbayWidget) to manage those placement parameters.
  ** 
  ** The HeaderPaneWidget aggregates those patchbay elements into a nested, collapsable tree
  ** structure in accordance with the nesting of scopes. For the actual layout, it has to collaborate

src/gui/timeline/timeline-widget.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file timeline-widget.cpp
+/** @file timeline/timeline-widget.cpp
  ** Implementation details of Lumiera's timeline display widget.
  ** 
  ** @todo as of 12/2016 a complete rework of the timeline display is underway

src/gui/timeline/timeline-widget.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file timeline-widget.hpp
+/** @file timeline/timeline-widget.hpp
  ** This file defines the core component of the Lumiera GUI.
  ** Timelines are the top level elements within Lumiera's high-level-model ("the session").
  ** In the UI workspace, there is a timeline pane with several tabs, each of which holds an

src/gui/widget/bin-widget.hpp

@@ -26,9 +26,9 @@
  ** A media bin is a grouping device, used in the asset management section
  ** to organise various "things", like clips, media, effect plugins, labels
  ** sequences, processing patterns and also other nested bins. In the Lumiera
- ** session model, media bins and tracks are visual renderings of the same
- ** entity, a [grouping fork](\ref session::Fork). This wide array of possible
- ** usage gives rise to some complexity and several display styles, ranging
+ ** session model, media bins and tracks are visual renderings of the same entity,
+ ** a [grouping fork](\ref proc::mobject::session::Fork). This wide array of
+ ** possible usage gives rise to some complexity and several display styles, ranging
  ** from a simple list to a working area to arrange elements, with drag-n-drop
  ** support, searching and establishing of an element order. The generality
  ** of this element and the shared common implementation are intentional;

src/gui/widget/timeline-widget.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file timeline-widget.cpp
+/** @file widget/timeline-widget.cpp
  ** 
  ** @deprecated as of 11/2016, a complete rework of the timeline display is underway
  ** @see gui::timeline::TimelineWidget new timeline display

src/gui/widget/timeline-widget.hpp

@@ -20,7 +20,7 @@
 
 */
 
-/** @file timeline-widget.hpp
+/** @file widget/timeline-widget.hpp
  ** This file defines the core component of the Lumiera GUI
  ** 
  ** @deprecated broken since transition to GTK-3

src/gui/widget/timeline/timeline-state.hpp

@@ -130,7 +130,7 @@ namespace gui {
       
       
       /** is there currently any ongoing playback process?
-       *  Otherwise the #getPlaybackPoint is meaningless */
+       *  Otherwise the #getPlaybackPoint() is meaningless */
       bool isPlaying() const { return isPlayback_; }
       
       void setSelectionControl (SelectionControl &control);

src/include/config-facade.h

@@ -20,7 +20,7 @@
 
 */
 
-/** @file configfacade.h
+/** @file config-facade.h
  ** The lumiera::Config wrapper class addresses two issues.
  ** First, it registers startup and shutdown hooks to bring up the config system
  ** as early as possible. Later, on application main initialisation, the global

src/include/display-handles.h

@@ -20,7 +20,7 @@
 
 */
 
-/** @file display-handles.hpp
+/** @file display-handles.h
  ** Opaque handles and similar typedefs used to communicate via the
  ** lumiera::Display and lumiera::DummyPlayer facade interfaces.
  **

src/include/logging.h

@@ -54,7 +54,7 @@
  ** Any log level can be overridden by an environment variable, for example
  ** `NOBUG_LOG='progress:INFO' ./lumiera`
  **
- ** @todo logging to files?    NOBUG_LOG='progress:INFO@file(name=filename)' api to set this statically up by the program will follow  --cehteh
+ ** @todo logging to files? `NOBUG_LOG='progress:INFO@file(name=filename)'` api to set this statically up by the program will follow  --cehteh
  */
 
 

src/lib/condition.h

@@ -164,7 +164,7 @@ typedef lumiera_condition* LumieraCondition;
 
 
 /**
- * Initialize a condition variable
+ * Initialise a condition variable
  * @param self is a pointer to the condition variable to be initialised
  * @return self as given
  */

src/lib/diff/diff-mutable.hpp

@@ -81,9 +81,9 @@ namespace diff{
        *  suitably wired to cause appropriate changes to the opaque
        *  data structure, in accordance to the semantics of the
        *  tree diff language.
-       * @param a buffer handle, which can be used to placement-construct
+       * @param buffer a buffer handle, which can be used to placement-construct
        */
-      virtual void buildMutator (TreeMutator::Handle)    =0;
+      virtual void buildMutator (TreeMutator::Handle buffer)    =0;
     };
   
   

src/lib/diff/list-diff-application.hpp

@@ -25,9 +25,9 @@
  ** Apply a "list diff" to a concrete sequence of elements in a container.
  ** This header provides specialisation(s) of the DiffApplicationStrategy to
  ** actual containers, choosing an implementation approach suitable for this
- ** specific kind of container. Together with a #DiffApplicator, this allows
- ** to receive the description of changes (as a linearised sequence of
- ** DiffStep tokens) and apply them to a given concrete sequence of data
+ ** specific kind of container. Together with a lib::diff::DiffApplicator,
+ ** this allows to receive the description of changes (as a linearised sequence
+ ** of DiffStep tokens) and apply them to a given concrete sequence of data
  ** elements, thereby transforming the contents of this target sequence.
  ** 
  ** @see diff-list-application-test.cpp

src/lib/diff/list-diff.hpp

@@ -23,10 +23,10 @@
 
 /** @file list-diff.hpp
  ** A token language to represent changes in a list of elements.
- ** In combination with the #DiffLanguage framework, this building block
- ** defines the set of operations to express changes in a given list of elements.
- ** By implementing the #ListDiffInterpreter interface (visitor), a concrete usage
- ** can receive such a diff description and e.g. apply it to a target data structure.
+ ** In combination with the [DiffLanguage framework](diff-langue.hpp), this building
+ ** block defines the set of operations to express changes in a given list of elements.
+ ** By implementing the lib::diff::ListDiffInterpreter interface (visitor), a concrete
+ ** usage can receive such a diff description and e.g. apply it to a target data structure.
  ** 
  ** @see diff-language.cpp
  ** @see diff-list-application-test.cpp

src/lib/format-cout.hpp

@@ -44,7 +44,7 @@
  ** 
  ** @see FormatCOUT_test
  ** @see FormatHelper_test
- ** @see [generic string conversion helper](\ref util::toString)
+ ** @see [generic string conversion helper](\ref util::toString() )
  ** @see [frontend for boost::format, printf-style](format-string.hpp)
  ** 
  */

src/lib/hash-fnv.h

@@ -53,7 +53,7 @@ hash_fnv64a_buf (const void *buf, size_t len, uint64_t hval);
 
 /**
  * FNV-1a 64 bit hash over a zero terminated string.
- * @param buf start of the buffer
+ * @param str start of the buffer
  * @param len maximum size to be processed
  * @param hval previous hash value when incremental hashing or HASH_FNV64_BASE when starting a new hash
  * @return new hash value
@@ -75,7 +75,7 @@ hash_fnv32a_buf (const void *buf, size_t len, uint32_t hval);
 
 /**
  * FNV-1a 32 bit hash over a zero terminated string.
- * @param buf start of the buffer
+ * @param str start of the buffer
  * @param len maximum size to be processed
  * @param hval previous hash value when incremental hashing or HASH_FNV32_BASE when starting a new hash
  * @return new hash value

src/lib/hash-standard.hpp

@@ -49,9 +49,9 @@
  ** @note this trick was proposed by user "enobayram" on Stackoverflow at Oct 5, 2012
  ** http://stackoverflow.com/questions/12753997/check-if-type-is-hashable
  ** 
- ** @warning this header <b>includes and manipulates</b> the standard header \c <functional>. Please
- **       ensure it is always included \em before the latter. Failing to do so will result in
- **       mysterious failures.
+ ** @warning this header <b>includes and manipulates</b> the standard header `<functional>`.
+ **       Please ensure it is always included _before_ the latter. Failing to do so will result
+ **       in mysterious failures.
  ** 
  ** @todo 4/2014 doesn't work as expected. My suspicion is that in the actual use case (PlacementIndex),
  **       the type providing the hasher is mixed in through inheritance, and the template specialisation

src/lib/iter-cursor.hpp

@@ -27,7 +27,7 @@
  ** to work in both directions, similar to std::reverse_iterator.
  ** Yet it is a single, self-contained element and in compliance to the
  ** ["Lumiera Forward Iterator"](iter-adapter.hpp) concept. But it has
- ** the additional ability to [switch the working direction](\ref IterCursor::switchDir).
+ ** the additional ability to [switch the working direction](\ref IterCursor<IT>::switchDir).
  ** 
  ** @see IterCursor_test
  ** @see iter-adapter.hpp

src/lib/llist.h

@@ -40,8 +40,8 @@
  *
  * This header can be used in 2 different ways:
  * 1) (preferred) just including it provides all functions as static inlined functions. This is the default
- * 2) #define LLIST_INTERFACE before including this header gives only the declarations
- *    #define LLIST_IMPLEMENTATION before including this header yields in definitions
+ * 2) `#define LLIST_INTERFACE` before including this header gives only the declarations
+ *    `#define LLIST_IMPLEMENTATION` before including this header yields in definitions
  *    this can be used to generate a library. This is currently untested and not recommended.
  * The rationale for using inlined functions is that most functions are very small and likely to be used in performance critical parts.
  * Inlining can give a huge performance and optimisation improvement here.

src/lib/meta/duck-detector.hpp

@@ -25,10 +25,10 @@
  ** Metaprogramming helpers to check for specific properties of a type in question.
  ** Building upon the "SFINAE" principle, it is possible to create \em metafunction templates,
  ** which answer some questions about a given type at compile time. A lot of generic predicates of
- ** this kind can be found in the \c <type_traits> library (standard since C++11). At times though,
+ ** this kind can be found in the `<type_traits>` library (standard since C++11). At times though,
  ** you want to ask more specific questions, like e.g. "does this type provide an operation quack() "?
- ** Because, if we can get a \c bool answer to such a question <i>at compile time,</i> we can use
- ** \c boost::enable_if to pick a special implementation based on the test result. Together, these
+ ** Because, if we can get a `bool` answer to such a question _at compile time,_ we can use
+ ** `std::enable_if` to pick a special implementation based on the test result. Together, these
  ** techniques allow to adopt a duck-typed programming style, where an arbitrary object is allowed
  ** to enter a given API function, provided this object supports some specific operations.
  ** 
@@ -37,7 +37,7 @@
  ** static type safety, which is compelling. (The downside is the danger of code bloat, as is with all
  ** template based techniques).
  ** 
- ** \par how the implementation works
+ ** # how the implementation works
  ** 
  ** Most of these trait templates rely on a creative use of function overloading. The C++ standard
  ** requires the compiler <i>silently to drop</i> any candidate of overload resolution which has
@@ -47,26 +47,26 @@
  ** out the overload actually picked by the compiler.
  ** 
  ** This header provides some pre-configured tests, available as macros. Each of them contains
- ** a template based on the described setup, containing a \em probe type expression at some point.
+ ** a template based on the described setup, containing a _probe type expression_ at some point.
  ** The key is to build this probe expression in a way that it is valid if and only if the
  ** type in question exhibits a specific property.
  ** 
  ** - if the type should contain a nested type or typedef with a specific name, we simply use
  **   this nested type in the signature of the overloaded function
- ** - if the type should contain a \em member with a specific name, we initialise a member pointer
+ ** - if the type should contain a _member_ with a specific name, we initialise a member pointer
  **   within a probe template with this member (if there isn't such a member, the probe template
  **   initialisation fails and the other function overload gets picked)
  ** - as an extension to this approach, we can even declare a member function pointer with a
  **   specific function signature and then try to assign the named member. This allows even
  **   to determine if a member function of a type in question has the desired signature.
  ** 
- ** All these detection building blocks are written such as to provide a bool member \c ::value,
+ ** All these detection building blocks are written such as to provide a bool member `::value`,
  ** which is in accordance to the conventions of boost metaprogramming. I.e. you can immediately
- ** use them within \c boost::enable_if
+ ** use them within `std::enable_if`
  ** 
- ** \par some pitfalls to consider
+ ** # some pitfalls to consider
  ** 
- ** @warning The generated metafunctions all yield the \c false value by default.
+ ** @warning The generated metafunctions all yield the `false` value by default.
  **          Effectively this means that an error in the test expression might go unnoticed;
  **          you'd be better off explicitly checking the detection result by an unit test.
  ** 

src/lib/meta/function-closure.hpp

@@ -611,7 +611,7 @@ namespace func{
       typedef function<typename FunctionTypedef<Ret,ArgsR>::Sig> RightReducedFunc;
       
       
-      /** do a partial function application, closing the first arguments</br>
+      /** do a partial function application, closing the first arguments<br/>
        *  `f(a,b,c)->res  +  (a,b)`  yields  `f(c)->res`
        *  
        *  @param f   function, function pointer or functor

src/lib/meta/trait.hpp

@@ -28,8 +28,8 @@
  ** 
  ** \par unwrapping
  ** Strip away all kinds of type adornments, like const, reference, pointer, smart-ptr.
- ** The accompanying \ref unwrap() function can be used to accept "stuff packaged
- ** in various forms". The \ref Strip template packages this ability in various
+ ** The accompanying \ref lib::meta::unwrap() function can be used to accept "stuff
+ ** packaged in various forms". The \ref Strip template packages this ability in various
  ** degrees for metaprogramming
  ** @warning these helpers can be quite dangerous, as they silently break
  **          any protective barriers (including lifecycle managing smart-ptrs)
@@ -47,8 +47,8 @@
  ** concept from the standard library (`begin()` and `end()`)
  ** 
  ** @see MetaUtils_test
- ** @see \rem format-obj.hpp string representation for _anything_
- ** @see \ref lib/meta/utils.hpp very basic metaprogramming helpers
+ ** @see format-obj.hpp string representation for _anything_
+ ** @see meta/util.hpp very basic metaprogramming helpers
  ** @see typelist.hpp
  ** 
  */

src/lib/meta/util.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file util.hpp
+/** @file meta/util.hpp
  ** Simple and lightweight helpers for metaprogramming and type detection.
  ** This header is a collection of very basic type detection and metaprogramming utilities.
  ** @warning indirectly, this header gets included into the majority of compilation units.

src/lib/priqueue.h

@@ -134,7 +134,7 @@ lumiera_priqueue_insert (LumieraPriQueue self, void* element);
 
 
 /**
- * @return pointer to the topmost element, \NULL on empty queue
+ * @return pointer to the topmost element, `NULL` on empty queue
  * @note returned pointer is only valid as long
  *       as no insert or remove is called
  */

src/lib/time/diagnostics.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file diagnostics.hpp
+/** @file time/diagnostics.hpp
  ** Extension to the lib::time::Time wrapper, adding output and further
  ** diagnostic aids. This shouldn't be confused with formatting into
  ** distinctive \em Timecode formats. There is an elaborate framework

src/lib/util.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file util.hpp
+/** @file lib/util.hpp
  ** Tiny helper functions and shortcuts to be used _everywhere_
  ** Consider this header to be effectively included in almost every translation unit.
  ** @remark The motivation of using these helpers is conciseness and uniformity of expression.

src/proc/asset/clip.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file clip.cpp
+/** @file asset/clip.cpp
  ** Clip Asset implementation
  */
 

src/proc/asset/clip.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file clip.hpp
+/** @file asset/clip.hpp
  ** Definition of Asset representation for a media clip
  */
 

src/proc/asset/effect.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file effect.cpp
+/** @file asset/effect.cpp
  ** Implementation level functionality regarding the Asset representation of effects
  ** @todo still unimplemented and stalled work as of 2016
  */

src/proc/asset/effect.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file effect.hpp
+/** @file asset/effect.hpp
  ** Definition of an Asset representation for any kind of _effect_ or media processor.
  */
 

src/proc/asset/meta.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file meta.cpp
+/** @file asset/meta.cpp
  ** Implementation details regarding the Meta Asset category
  */
 

src/proc/asset/meta.hpp

@@ -21,11 +21,11 @@
 */
 
 
-/** @file meta.hpp
+/** @file asset/meta.hpp
  ** Internal and organisational metadata. Some internally created data elements
  ** rather serve the purpose of controlling the way the application behaves, as
- ** opposed to organising the \link struct.hpp structure \endlink of the data the
- ** user works with. Lumiera exposes this self-referential control and customisation
+ ** opposed to organising the [structure](\ref struct.hpp) of the data the user
+ ** works with. Lumiera exposes this self-referential control and customisation
  ** aspects as a special kind of Asset. Examples being types, scales and quantisation
  ** grids, decision rules, control data stores (automation data), annotations attached
  ** to labels, inventory entities etc. 

src/proc/asset/sequence.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file sequence.cpp
+/** @file asset/sequence.cpp
  ** Implementation parts of the Sequence entity within the Session model
  */
 

src/proc/asset/sequence.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file sequence.hpp
+/** @file asset/sequence.hpp
  ** Structural building block of the session: a sequence of clips.
  ** A Sequence is both a structural element of the session and part of the
  ** public session API exposed to clients for discovering the session contents

src/proc/common.hpp

@@ -22,7 +22,7 @@
 
 */
 
-/** @file common.hpp
+/** @file proc/common.hpp
  ** Basic set of definitions and includes commonly used together.
  ** Including common.hpp gives you a common set of elementary declarations
  ** widely used within the C++ code of the Proc-Layer. Besides that, this

src/proc/config-resolver.hpp

@@ -26,10 +26,10 @@
  ** Definition of the concrete frontend for rule based configuration within the session.
  ** 
  ** @remarks This code will act as a hub to pull in, instrument and activate a lot of further code.
- **          All the types mentioned in the #InterfaceTypes typelist will be prepared to be used
+ **          All the types mentioned in the proc::InterfaceTypes typelist will be prepared to be used
  **          in rules based setup and configuration; this definition will drive the generation of
  **          all the necessary bindings and registration entries to make this work. This is in
- **          accordance with the principle of <i>generic programming:</i> Instead of making things
+ **          accordance with the principle of *generic programming*: Instead of making things
  **          uniform, we use related things in a similar manner.
  ** @note this is placeholder code using a preliminary/mock implementation... don't take this code too literal!
  ** @todo clarify the relation of config query and query-for-defaults   ///////////////TICKET #705

src/proc/control/styperegistry.hpp

@@ -22,7 +22,7 @@
 
 
 /** @file styperegistry.hpp
- ** This is part of the \i implementation of the stream type manager (include).
+ ** This is part of the _implementation_ of the stream type manager (include).
  ** Only used in stypemanager.cpp and accompanying unit tests.
  ** 
  ** @see control::STypeManager

src/proc/engine/buffer-metadata.hpp

@@ -20,7 +20,7 @@
 
 */
 
-/** @file buffer-metadate.hpp
+/** @file buffer-metadata.hpp
  ** Metadata for managing and accessing buffers. The Lumiera Engine uses the
  ** Abstraction of an BufferProvider to handle various kinds of buffer organisation
  ** and access in a uniform way. Actually, buffers can be exposed and provided by several

src/proc/engine/engine-service.hpp

@@ -96,7 +96,6 @@ namespace engine{
    * responsible for creating the right job entries in the
    * correct order and to enqueue these into the scheduler.
    * @ingroup engine
-   * @ingroup player
    */
   class EngineService
     : boost::noncopyable

src/proc/engine/job-planning.hpp

@@ -34,7 +34,7 @@
  ** - JobPlanningSequence is the entry point for client code: it allows to generate a sequence of jobs
  ** - JobPlanning is a view on top of all the collected planning information for a single job
  ** - PlanningState is an iterator, successively exposing a sequence of JobPlanning views
- ** - #expandPrerequisites(JobPlanning const&) is the operation to explore further prerequisite Jobs recursively
+ ** - proc::engine::expandPrerequisites(JobPlanning const&) is the operation to explore further prerequisite Jobs recursively
  ** - PlanningStepGenerator yields the underlying "master beat": a sequence of frame locations to be planned
  ** 
  ** \par how the PlanningState (sequence) is advanced

src/proc/mobject/builder/buildertool.hpp

@@ -29,18 +29,17 @@
  ** As the objects to be treated are normally handled by smart-ptrs, BuilderTool provides
  ** a special facility for dealing with these wrapped objects. There are some liabilities.
  ** - each concrete Buildable subtype to be treated specifically needs to
- **   declare \c DEFINE_PROCESSABLE_BY(BuilderTool)
+ **   declare `DEFINE_PROCESSABLE_BY(BuilderTool)`
  ** - at the same time, the concrete BuilderTool subclass has to declare
  **   being Applicable to this concrete Buildable subtype. The recommended way
  **   of ensuring this, is to add an entry to applicable-builder-target-types.hpp
  **   and then derive the concrete BuilderTool subclass from 
  **   ApplicableBuilderTargetTypes
- ** - when accessing the wrapper from within a \c treat() function, a suitable
+ ** - when accessing the wrapper from within a `treat()` function, a suitable
  **   concrete wrapper type has to be specified. If the wrapper type used for
- **   invoking the BuilderTool (function \c apply(BuilderTool&l, WrappedObject&) )
+ **   invoking the BuilderTool (function `apply(BuilderTool&, WrappedObject&)`)
  **   can not be converted to this type requested from within the call, an 
  **   assertion failure (or segmentation fault in a release build) will result.
- ** </ul>   
  ** 
  ** @see visitor.hpp
  ** @see applicable-builder-target-types.hpp

src/proc/mobject/builder/common.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file common.hpp
+/** @file builder/common.hpp
  ** @todo initially generated code of unclear relevance
  ** @deprecated 2016 is a common inclusion file really such a good idea?
  */

src/proc/mobject/builder/segmentation.cpp

@@ -1,86 +0,0 @@
-/*
-  Segmentation  -  partitioning the effective timeline
-
-  Copyright (C)         Lumiera.org
-    2010,               Hermann Vosseler <Ichthyostega@web.de>
-
-  This program is free software; you can redistribute it and/or
-  modify it under the terms of the GNU General Public License as
-  published by the Free Software Foundation; either version 2 of
-  the License, or (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program; if not, write to the Free Software
-  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-* *****************************************************/
-
-
-/** @file segmentation.cpp
- ** Implementation details of fixture data structures.
- ** 
- ** /////TODO file comment necessary?
- ** 
- ** @see mobject::session::Fixture
- **
- */
-
-
-#include "lib/error.hpp"
-//#include "include/logging.h"
-//#include "lib/sync-classlock.hpp"
-//#include "proc/mobject/builderfacade.hpp"
-#include "proc/mobject/builder/segmentation.hpp"
-#include "proc/mobject/builder/fixture-change-detector.hpp"
-
-namespace proc {
-namespace mobject {
-namespace builder {
-  
-  namespace error = lumiera::error;
-  
-  
-//  typedef ModelPortRegistry::ModelPortDescriptor const& MPDescriptor;
-  
-  
-  /** storage for the link to the global
-      Registry instance currently in charge  */
-//  lib::OptionalRef<ModelPortRegistry> ModelPortRegistry::theGlobalRegistry;
-  
-  
-  /** access the globally valid registry instance.
-   *  @throw error::State if this global registry is
-   *         already closed or not yet initialised. */
-//ModelPortRegistry&
-//ModelPortRegistry::globalInstance()
-//{
-//  LockRegistry global_lock;
-//  if (theGlobalRegistry.isValid())
-//    return theGlobalRegistry();
-//  
-//  throw error::State ("global model port registry is not accessible"
-//                     , LUMIERA_ERROR_BUILDER_LIFECYCLE); 
-//}
-  
-  
-  
-  /** */
-//  bool
-//  ModelPortRegistry::contains (ID<Pipe> key)  const
-//  {
-//    return bool(key)
-//        && util::contains (transaction_, key); 
-//  }
-  
-  
-  
-//LUMIERA_ERROR_DEFINE (DUPLICATE_MODEL_PORT, "Attempt to define a new model port with an pipe-ID already denoting an existing port");
-  
-  
-  
-}}}// namespace proc::mobject::builder

src/proc/mobject/builder/segmentation.hpp

@@ -1,89 +0,0 @@
-/*
-    SEGMENTATION.hpp  -  partitioning the effective timeline
-
-  Copyright (C)         Lumiera.org
-    2010,               Hermann Vosseler <Ichthyostega@web.de>
-
-  This program is free software; you can redistribute it and/or
-  modify it under the terms of the GNU General Public License as
-  published by the Free Software Foundation; either version 2 of
-  the License, or (at your option) any later version.
-
-  This program is distributed in the hope that it will be useful,
-  but WITHOUT ANY WARRANTY; without even the implied warranty of
-  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-  GNU General Public License for more details.
-
-  You should have received a copy of the GNU General Public License
-  along with this program; if not, write to the Free Software
-  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-*/
-
-/** @file segmentation.hpp
- ** Part of the Fixture datastructure to manage time segments of constant structure.
- ** The Fixture is result of the build process and separation between high-level and
- ** low-level model. It's kind of an effective resulting timeline, and split into segments
- ** of constant wiring structure: whenever the processing nodes need to be wired differently
- ** for some timespan, we start a new segment of the timeline. This might be for the duration
- ** of a clip, or just for the duration of a transition, when the pipes of both clips need to
- ** be wired up in parallel.
- ** 
- ** @see Fixture
- ** @see ModelPort
- */
-
-
-#ifndef PROC_MOBJECT_BUILDER_SEGMENTATION_H
-#define PROC_MOBJECT_BUILDER_SEGMENTATION_H
-
-#include "lib/error.hpp"
-//#include "lib/optional-ref.hpp"
-#include "proc/asset/pipe.hpp"
-//#include "proc/asset/struct.hpp"
-//#include "proc/mobject/model-port.hpp"
-
-//#include <map>
-
-namespace proc    {
-namespace mobject {
-namespace builder {
-  
-  using asset::ID;
-  using asset::Pipe;
-//using asset::Struct;
-  
-//LUMIERA_ERROR_DECLARE (DUPLICATE_MODEL_PORT); ///< Attempt to define a new model port with an pipe-ID already denoting an existing port
-  
-  
-  /**
-   * TODO type comment
-   */
-  class Segment
-    : boost::noncopyable
-    {
-      
-      /////////////////////////////////////////////////TODO: placeholder code
-      /////////////////////////////////////////////////TODO: see the planned structure at http://lumiera.org/wiki/renderengine.html#Fixture
-      typedef ID<Pipe>   PID;
-      
-    public:
-      
-    };
-  
-  
-  
-  
-  /** 
-   * TODO type comment
-   */
-  class Segmentation
-    {
-      
-    public:
-    };
-  
-  
-  
-}}} // namespace proc::mobject::builder
-#endif

src/proc/mobject/session/binding.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file binding.cpp
+/** @file session/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

src/proc/mobject/session/clip.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file clip.cpp
+/** @file session/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

src/proc/mobject/session/clip.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file clip.hpp
+/** @file session/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

src/proc/mobject/session/effect.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file effect.cpp
+/** @file session/effect.cpp
  ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 

src/proc/mobject/session/effect.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file effect.hpp
+/** @file session/effect.hpp
  ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... 
  */
 

src/proc/mobject/session/label.hpp

@@ -23,7 +23,7 @@
 
 /** @file label.hpp
  ** A marker or reference point in the Session.
- ** Label MObjects can be [placed](\ref Placement) at various locations and scopes,
+ ** Label MObjects can be [placed](\ref placement.hpp) 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.

src/proc/mobject/session/meta.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file meta.cpp
+/** @file session/meta.cpp
  ** implementation details regarding the Meta asset abstraction
  ** 
  ** @todo stalled effort towards a session implementation from 2008

src/proc/mobject/session/meta.hpp

@@ -21,7 +21,7 @@
 */
 
 
-/** @file meta.hpp
+/** @file session/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

src/proc/mobject/session/placement-index.cpp

@@ -387,7 +387,7 @@ namespace session {
       
       
       /** Helper for building a scope exploring iterator
-       *  for PlacementIndex: our "reverse index" (#scopeTab_)
+       *  for PlacementIndex: our "reverse index" (`scopeTab_`)
        *  tracks the contents of each scope as pairs (scopeID,elementID).
        *  After fetching the range of matching entries, whenever the client
        *  dereferences the iterator, we have to pick up the second ID and

src/proc/mobject/session/segmentation.cpp

@@ -26,7 +26,9 @@
  ** @todo 2016 likely to stay, but expect some extensive rework
  */
 
+#include "lib/error.hpp"
 #include "proc/mobject/session/segmentation.hpp"
+#include "proc/mobject/builder/fixture-change-detector.hpp"
 
 
 
@@ -34,7 +36,44 @@ namespace proc {
 namespace mobject {
 namespace session {
   
+  namespace error = lumiera::error;
+  
+  
+//  typedef ModelPortRegistry::ModelPortDescriptor const& MPDescriptor;
+  
+  
+  /** storage for the link to the global
+      Registry instance currently in charge  */
+//  lib::OptionalRef<ModelPortRegistry> ModelPortRegistry::theGlobalRegistry;
+  
+  
+  /** access the globally valid registry instance.
+   *  @throw error::State if this global registry is
+   *         already closed or not yet initialised. */
+//ModelPortRegistry&
+//ModelPortRegistry::globalInstance()
+//{
+//  LockRegistry global_lock;
+//  if (theGlobalRegistry.isValid())
+//    return theGlobalRegistry();
+//  
+//  throw error::State ("global model port registry is not accessible"
+//                     , LUMIERA_ERROR_BUILDER_LIFECYCLE); 
+//}
+  
+  
+  
   /** */
+//  bool
+//  ModelPortRegistry::contains (ID<Pipe> key)  const
+//  {
+//    return bool(key)
+//        && util::contains (transaction_, key); 
+//  }
+  
+  
+  
+//LUMIERA_ERROR_DEFINE (DUPLICATE_MODEL_PORT, "Attempt to define a new model port with an pipe-ID already denoting an existing port");
   
   
   

src/proc/mobject/session/segmentation.hpp

@@ -22,7 +22,14 @@
 
 
 /** @file segmentation.hpp
- ** A segment of the effective timeline, part of the low-level model backbone.
+ ** Part of the Fixture datastructure to manage time segments of constant structure.
+ ** The Fixture is result of the build process and separation between high-level and
+ ** low-level model. It's kind of an effective resulting timeline, and split into segments
+ ** of constant wiring structure: whenever the processing nodes need to be wired differently
+ ** for some timespan, we start a new segment of the timeline. This might be for the duration
+ ** of a clip, or just for the duration of a transition, when the pipes of both clips need to
+ ** be wired up in parallel.
+ ** 
  ** 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.
@@ -30,6 +37,9 @@
  ** 
  ** @todo stalled effort towards a session implementation from 2008
  ** @todo 2016 likely to stay, but expect some extensive rework
+ ** 
+ ** @see Fixture
+ ** @see ModelPort
  */
 
 

src/proc/mobject/session/session-services.cpp

@@ -112,7 +112,7 @@ namespace session {
   }
   
   
-  /** detach the denoted element from the model <i>including all children.</i>
+  /** detach the denoted element from the model _including all children._
    *  @return true if actually erased something
    *  @note when specifying model root, all sub-elements will be cleared,
    *        but model root itself will be retained. 

tests/basics/stream-type-basics-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file streamtypebasicstest.cpp
+/** @file stream-type-basics-test.cpp
  ** unit test \ref StreamTypeBasics_test
  */
 

tests/basics/stream-type-lifecycle-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file streamtypelifecycletest.cpp
+/** @file stream-type-lifecycle-test.cpp
  ** unit test \ref StreamTypeLifecycle_test
  */
 

tests/basics/visitingtool-concept.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file visitingtool-conept.cpp
+/** @file visitingtool-concept.cpp
  ** While laying the foundations for Session and Builder, Ichthyo came across
  ** the necessity to create a custom implementation of the Visitor Pattern
  ** optimally suited for Lumiera's needs. This implementation file was used

tests/core/backend/media-access-mock.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file mediaacessmock.cpp
+/** @file media-acess-mock.cpp
  ** Mock implementation of the Interface normally used to query media file
  ** information from the data backend. The Mock implementation instead holds
  ** a map of fixed response which will be delivered when querying some magic

tests/core/proc/asset/identity-of-assets-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file identityofassetstest.cpp
+/** @file identity-of-assets-test.cpp
  ** unit test \ref IdentityOfAssets_test
  */
 

tests/core/proc/asset/make-clip-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file makecliptest.cpp
+/** @file make-clip-test.cpp
  ** unit test \ref MakeClip_test
  */
 

tests/core/proc/asset/media-structure-query-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file mediastructurequerytest.cpp
+/** @file media-structure-query-test.cpp
  ** unit test \ref MediaStructureQuery_test
  */
 

tests/core/proc/asset/ordering-of-assets-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file orderingofassetstest.cpp
+/** @file ordering-of-assets-test.cpp
  ** unit test \ref OrderingOfAssets_test
  */
 

tests/core/proc/mobject/builder/build-segment-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file buildsegmenttest.cpp
+/** @file build-segment-test.cpp
  ** unit test \ref BuildSegment_test
  */
 

tests/core/proc/mobject/builder/builder-tool-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file buildertooltest.cpp
+/** @file builder-tool-test.cpp
  ** unit test \ref BuilderTool_test
  */
 

tests/core/proc/mobject/controller/render-segment-test.cpp

@@ -1,5 +1,5 @@
 /*
-  RenderSegment(Test)  -  Proc-Layer Integrationtest
+  RenderSegment(Test)  -  Proc-Layer integration test
 
   Copyright (C)         Lumiera.org
     2008,               Hermann Vosseler <Ichthyostega@web.de>
@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file rendersegmenttest.cpp
+/** @file render-segment-test.cpp
  ** unit test \ref RenderSegment_test
  */
 

tests/core/proc/mobject/session/add-clip-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file addcliptest.cpp
+/** @file add-clip-test.cpp
  ** unit test \ref AddClip_test
  */
 

tests/core/proc/mobject/session/session-manager-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file sessionmanagertest.cpp
+/** @file session-manager-test.cpp
  ** unit test \ref SessionManager_test
  */
 

tests/gui/test/test-nexus.cpp

@@ -455,7 +455,7 @@ namespace test{
   }
   
   /**
-   * similar to the [custom command handler](::setCommandHandler)
+   * similar to the [custom command handler](Nexus::setCommandHandler)
    * this hook allows to install a closure to intercept any
    * "state mark" messages passed over the test-UI-Bus
    */

tests/library/exception-error-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file exceptionerrortest.cpp
+/** @file exception-error-test.cpp
  ** unit test \ref ExceptionError_test
  */
 

tests/library/life-cycle-test.cpp

@@ -20,7 +20,7 @@
 
 * *****************************************************/
 
-/** @file lifecycletest.cpp
+/** @file life-cycle-test.cpp
  ** unit test \ref LifeCycle_test
  */
 

tests/library/meta/tuple-helper-test.cpp

@@ -21,7 +21,7 @@
 * *****************************************************/
 
 
-/** @file tuple-helpers-test.cpp
+/** @file tuple-helper-test.cpp
  ** Interplay of typelists, type tuples and std::tuple.
  ** 
  ** @see tuple-helper.hpp

tests/library/polymorphic-value-test.cpp

@@ -286,12 +286,12 @@ namespace test{
         }
       
       
-      /** @Test internally, PolymorphicValue uses some metafunctions
+      /** @test internally, PolymorphicValue uses some metafunctions
        * to pick a suitable code path, based on the presence of helper functions
        * on the API of the embedded objects. Default is no support by these objects,
        * which then requires to use a more expensive implementation. Sometimes it's
-       * desirable to support \em cloning only (copy ctor), but no assignment after
-       * the fact. In this special case, a support API with only a \cloneInto member
+       * desirable to support _cloning only_ (copy ctor), but no assignment after
+       * the fact. In this special case, a support API with only a `cloneInto()` member
        * can be implemented, causing the PolymorphicValue container to raise an 
        * exception in case the copy operator is invoked.
        */