diff --git a/src/common/advice/advice.cpp b/src/common/advice/advice.cpp
index 6271ad6ca..178b288cf 100644
--- a/src/common/advice/advice.cpp
+++ b/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,
diff --git a/src/common/advice/binding.cpp b/src/common/advice/binding.cpp
index b18436829..fae7f1df4 100644
--- a/src/common/advice/binding.cpp
+++ b/src/common/advice/binding.cpp
@@ -22,7 +22,11 @@
 
 
 /** @file binding.cpp
- ** TODO 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.
  */
 
 
@@ -62,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. */
diff --git a/src/common/advice/binding.hpp b/src/common/advice/binding.hpp
index 8b92bbd99..699e113db 100644
--- a/src/common/advice/binding.hpp
+++ b/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.
diff --git a/src/common/config-interface.c b/src/common/config-interface.c
index e2bbcd48c..d71196443 100644
--- a/src/common/config-interface.c
+++ b/src/common/config-interface.c
@@ -22,7 +22,10 @@
 
 
 /** @file config-interface.c
- ** TODO 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.
  */
 
 
diff --git a/src/common/config-interface.h b/src/common/config-interface.h
index ebca9d573..21b0a8691 100644
--- a/src/common/config-interface.h
+++ b/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
  */
 
diff --git a/src/common/config-lookup.c b/src/common/config-lookup.c
index a6603db60..58eda6359 100644
--- a/src/common/config-lookup.c
+++ b/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.
  */
 
 
diff --git a/src/common/config-lookup.h b/src/common/config-lookup.h
index ad512b354..0acff34c8 100644
--- a/src/common/config-lookup.h
+++ b/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.
  */
diff --git a/src/common/config-rules.hpp b/src/common/config-rules.hpp
index c583575ba..549fb1bc0 100644
--- a/src/common/config-rules.hpp
+++ b/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,
- ** for now we use a \link MockConfigRules mock implementation \endlink employing a
- ** preconfigured Map.
- **
+ ** 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
+ ** 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 
  **
  */
 
diff --git a/src/common/config-typed.c b/src/common/config-typed.c
index cbfd88c49..b7d38a26d 100644
--- a/src/common/config-typed.c
+++ b/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"
diff --git a/src/common/config-wordlist.c b/src/common/config-wordlist.c
index 2bc21f967..2c6a05d0e 100644
--- a/src/common/config-wordlist.c
+++ b/src/common/config-wordlist.c
@@ -22,7 +22,11 @@
 
 
 /** @file config-wordlist.c
- ** TODO 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.
  */
 
 
diff --git a/src/common/config.c b/src/common/config.c
index 7d70d255e..b08073356 100644
--- a/src/common/config.c
+++ b/src/common/config.c
@@ -22,7 +22,9 @@
 
 
 /** @file config.c
- ** TODO 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
  */
 
 
diff --git a/src/common/config.h b/src/common/config.h
index 0c08eb49e..82b6025ee 100644
--- a/src/common/config.h
+++ b/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
  */
diff --git a/src/common/configentry.c b/src/common/configentry.c
index 18336d9fe..ca74e083f 100644
--- a/src/common/configentry.c
+++ b/src/common/configentry.c
@@ -22,7 +22,9 @@
 
 
 /** @file configentry.c
- ** TODO 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.
  */
 
 
diff --git a/src/common/configentry.h b/src/common/configentry.h
index 066119148..8a7eb0682 100644
--- a/src/common/configentry.h
+++ b/src/common/configentry.h
@@ -22,7 +22,9 @@
 
 
 /** @file configentry.h
- ** TODO 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.
  */
 
 
diff --git a/src/common/configfacade.cpp b/src/common/configfacade.cpp
index cdaaebd0e..ac7500be5 100644
--- a/src/common/configfacade.cpp
+++ b/src/common/configfacade.cpp
@@ -22,7 +22,20 @@
 
 
 /** @file configfacade.cpp
- ** TODO 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)
  */
 
 
diff --git a/src/common/configitem.c b/src/common/configitem.c
index 01850af4d..0fe3cbd6d 100644
--- a/src/common/configitem.c
+++ b/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.
  */
 
 
diff --git a/src/common/configitem.h b/src/common/configitem.h
index 3781dbcd6..dd0784164 100644
--- a/src/common/configitem.h
+++ b/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
diff --git a/src/common/query/config-rules.cpp b/src/common/query/config-rules.cpp
index a7a7149df..ac2e6e6aa 100644
--- a/src/common/query/config-rules.cpp
+++ b/src/common/query/config-rules.cpp
@@ -23,7 +23,8 @@
 
 
 /** @file config-rules.cpp
- ** TODO config-rules.cpp
+ ** Implementation backend part for a configuration rules / query system.
+ ** @todo placeholder and mostly not implemented as of 11/2016
  */
 
 
diff --git a/src/common/query/defs-manager.hpp b/src/common/query/defs-manager.hpp
index 16fb2baba..9800f7834 100644
--- a/src/common/query/defs-manager.hpp
+++ b/src/common/query/defs-manager.hpp
@@ -22,7 +22,72 @@
 
 
 /** @file defs-manager.hpp
- ** TODO 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
+ ** 
  */
 
 
diff --git a/src/common/query/defs-registry.hpp b/src/common/query/defs-registry.hpp
index a4449d328..f161f2e8a 100644
--- a/src/common/query/defs-registry.hpp
+++ b/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. 
diff --git a/src/common/query/query-resolver.cpp b/src/common/query/query-resolver.cpp
index 2d974c556..358414a5f 100644
--- a/src/common/query/query-resolver.cpp
+++ b/src/common/query/query-resolver.cpp
@@ -22,7 +22,14 @@
 
 
 /** @file query-resolver.cpp
- ** TODO 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.
+ ** 
  */
 
 
@@ -102,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);
   }
diff --git a/src/common/query/query-resolver.hpp b/src/common/query/query-resolver.hpp
index f7f831c73..3850fb215 100644
--- a/src/common/query/query-resolver.hpp
+++ b/src/common/query/query-resolver.hpp
@@ -22,7 +22,13 @@
 
 
 /** @file query-resolver.hpp
- ** TODO 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"
+ ** 
  */
 
 
diff --git a/src/include/config-facade.h b/src/include/config-facade.h
index 6beb6b95a..43dcce424 100644
--- a/src/include/config-facade.h
+++ b/src/include/config-facade.h
@@ -26,9 +26,17 @@
  ** as early as possible. Later, on application main initialisation, the global
  ** config interface is opened and wrapped for convenient access from C++ code.
  ** 
+ ** @note 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".
+ ** @warning as a preliminary solution, the original configuration system draft
+ **       was detached and replaced by an _ini file solution_ based on lib Boost.
+ ** 
  ** @todo there ought to be an external Interface for the Config subsystem.
  **       But the full-blown Config system isn't implemented yet anyway
- **
+ ** 
  ** @see config.h
  ** @see lumiera::AppState
  ** @see main.cpp