Doxygen: fill in missing file level headlines for config and query frameworks

Added warning tags to several headers of the first config system draft from 2008
since this effort is stalled and likely to be implemented differently

src/common/advice/advice.cpp

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

src/common/advice/binding.cpp

@@ -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. */

src/common/advice/binding.hpp

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

src/common/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.
  */
 
 

src/common/config-interface.h

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

src/common/config-lookup.c

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

src/common/config-lookup.h

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

src/common/config-rules.hpp

@@ -26,10 +26,10 @@
  ** By using the Query template, you can pose a query in prolog syntax and get some
  ** existing or newly created object fulfilling the requested predicates. The actual 
  ** implementation is hidden behind the #instance (Singleton factory). As of 1/2008, 
- ** it is \e planned to use an embedded YAP Prolog system at some point in the future,
- ** 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 
  **
  */
 

src/common/config-typed.c

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

src/common/config-wordlist.c

@@ -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.
  */
 
 

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
  */
 
 

src/common/config.h

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

src/common/configentry.c

@@ -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.
  */
 
 

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.
  */
 
 

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)
  */
 
 

src/common/configitem.c

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

src/common/configitem.h

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

src/common/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
  */
 
 

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
+ ** 
  */
 
 

src/common/query/defs-registry.hpp

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

src/common/query/query-resolver.cpp

@@ -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);
   }

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"
+ ** 
  */
 
 

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