diff --git a/src/backend/backend.c b/src/backend/backend.c index 87b8ee42d..a0f909b35 100644 --- a/src/backend/backend.c +++ b/src/backend/backend.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file backend.c + ** Lumiera Backend: implementation of global initialisation and services. + */ + + #include "include/logging.h" #include "lib/safeclib.h" #include "lib/tmpbuf.h" diff --git a/src/backend/backend.h b/src/backend/backend.h index e8b5f7b7b..5eb00217f 100644 --- a/src/backend/backend.h +++ b/src/backend/backend.h @@ -21,6 +21,11 @@ */ +/** @file backend.h + ** Lumiera Backend: global initialisation and definitions. + */ + + #ifndef BACKEND_BACKEND_H #define BACKEND_BACKEND_H diff --git a/src/backend/engine/engine-config.cpp b/src/backend/engine/engine-config.cpp index f66d2de27..93b10528f 100644 --- a/src/backend/engine/engine-config.cpp +++ b/src/backend/engine/engine-config.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file engine-config.cpp + ** implementation of engine configuration and parametrisation + */ + + #include "backend/engine/engine-config.h" #include "lib/time/timevalue.hpp" diff --git a/src/backend/engine/engine-config.h b/src/backend/engine/engine-config.h index 15459ef10..89df108a9 100644 --- a/src/backend/engine/engine-config.h +++ b/src/backend/engine/engine-config.h @@ -21,6 +21,11 @@ */ +/** @file engine-config.h + ** access point to configuration of engine parameters + */ + + #ifndef BACKEND_ENGINE_ENGINE_CONFIG_H #define BACKEND_ENGINE_ENGINE_CONFIG_H diff --git a/src/backend/engine/job.h b/src/backend/engine/job.h index 43b6d57d2..cd77fcb7f 100644 --- a/src/backend/engine/job.h +++ b/src/backend/engine/job.h @@ -27,12 +27,12 @@ ** for time bound invocation. This header defines the data structures used to describe ** a job, and the basic data structures used by the scheduler to keep track of individual ** jobs. Moreover, within the C++ part of this header, some classes are layered on top - ** of these data structures; especially the JobClosure ABC describes the \em generic part + ** of these data structures; especially the JobClosure ABC describes the _generic part_ ** of each job, while the "moving parts" are embedded within the lumiera_jobParameter. ** ** A render job is a parameterless function, ready to be invoked by the scheduler.. ** Since every non trivial job actually needs some parameters (at least a frame number) - ** and relies on additional definitions and data structures, a \em closure is created + ** and relies on additional definitions and data structures, a _closure_ is created ** to make these dependencies explicit and opaque for the scheduler. The actual ** job invocation is forwarded to a virtual function JobClosure#invokeJobOperation(JobParameter), ** which is defined "somewhere" in a subclass and remains opaque for the scheduler; diff --git a/src/backend/engine/scheduler-frontend.cpp b/src/backend/engine/scheduler-frontend.cpp index 629849492..7e4aff0c1 100644 --- a/src/backend/engine/scheduler-frontend.cpp +++ b/src/backend/engine/scheduler-frontend.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file scheduler-frontend.cpp + ** Scheduler service implementation + */ + + #include "lib/error.h" #include "backend/engine/scheduler-frontend.hpp" diff --git a/src/backend/engine/scheduler-frontend.hpp b/src/backend/engine/scheduler-frontend.hpp index 1b0b23cce..d0c841be9 100644 --- a/src/backend/engine/scheduler-frontend.hpp +++ b/src/backend/engine/scheduler-frontend.hpp @@ -21,6 +21,12 @@ */ +/** @file scheduler-frontend.hpp + ** Scheduler service access point for higher layers. + ** @todo WIP unfinished since 9/2013 + */ + + #ifndef BACKEND_ENGINE_SCHEDULER_FRONTEND_H #define BACKEND_ENGINE_SCHEDULER_FRONTEND_H diff --git a/src/backend/enginefacade.cpp b/src/backend/enginefacade.cpp index b261a5d8b..a6ac186f6 100644 --- a/src/backend/enginefacade.cpp +++ b/src/backend/enginefacade.cpp @@ -21,6 +21,17 @@ * *****************************************************/ +/** @file enginefacade.cpp + ** Subsystem descriptor and configuration for the render engine. + ** This is the implementation part to manage render engine lifecycle + ** as a Subsystem of the whole application. + ** + ** @todo placeholder/draft as of 1/2017 + ** @see main.cpp + ** + */ + + #include "backend/enginefacade.hpp" #include "lib/depend.hpp" diff --git a/src/backend/enginefacade.hpp b/src/backend/enginefacade.hpp index 64717e567..1d0634f59 100644 --- a/src/backend/enginefacade.hpp +++ b/src/backend/enginefacade.hpp @@ -21,6 +21,14 @@ */ +/** @file enginefacade.hpp + ** Global control interface for the render engine subsystem. + ** The render engine, as implemented in an combined effort by the + ** Lumiera backend and some parts of Proc-Layer, can be started and + ** stopped as a [Subsystem](\ref subsys.hpp) of the whole application. + */ + + #ifndef BACKEND_INTERFACE_ENGINEFACADE_H #define BACKEND_INTERFACE_ENGINEFACADE_H diff --git a/src/backend/file-handling.c b/src/backend/file-handling.c index df5326ded..1fd1a3861 100644 --- a/src/backend/file-handling.c +++ b/src/backend/file-handling.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file file-handling.c + ** Implementation of file management functions + */ + + #include "include/logging.h" #include "lib/mutex.h" #include "lib/safeclib.h" diff --git a/src/backend/filedescriptor.c b/src/backend/filedescriptor.c index b7320bf1c..180bd5d13 100644 --- a/src/backend/filedescriptor.c +++ b/src/backend/filedescriptor.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file filedescriptor.c + ** Implementation of a file descriptor management framework + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/mutex.h" #include "lib/safeclib.h" @@ -78,7 +84,7 @@ lumiera_filedescriptor_acquire (const char* name, int flags, LList filenode) } int fd; INFO (filedescriptor_dbg, "try creating file: %s", name); - TODO ("creat mode from config"); + TODO ("create mode from config"); fd = creat (name, 0666); if (fd == -1) { diff --git a/src/backend/filedescriptorregistry.c b/src/backend/filedescriptorregistry.c index 9f7100de9..8717d25e4 100644 --- a/src/backend/filedescriptorregistry.c +++ b/src/backend/filedescriptorregistry.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file filedescriptorregistry.c + ** Implementation of a registry to manage used filedescriptors + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/safeclib.h" #include "lib/mutex.h" diff --git a/src/backend/filehandle.c b/src/backend/filehandle.c index 4f17f295a..4557bc558 100644 --- a/src/backend/filehandle.c +++ b/src/backend/filehandle.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file filehandle.c + ** Implementation of filehandle representation. + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/llist.h" #include "lib/safeclib.h" diff --git a/src/backend/filehandlecache.c b/src/backend/filehandlecache.c index b45bdf42c..2cd0046e5 100644 --- a/src/backend/filehandlecache.c +++ b/src/backend/filehandlecache.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file filehandlecache.c + ** Implementation of caching for filehandle representation data + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/safeclib.h" diff --git a/src/backend/fileheader.c b/src/backend/fileheader.c index c248acded..1fe269d76 100644 --- a/src/backend/fileheader.c +++ b/src/backend/fileheader.c @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file fileheader.c + ** Implementation of a common header format for working data files created + ** by the lumiera backend. + ** @todo development in this area is stalled since 2010 + */ + + #include "lib/tmpbuf.h" #include "backend/fileheader.h" diff --git a/src/backend/media-access-facade.cpp b/src/backend/media-access-facade.cpp index d35a8a1e1..889150272 100644 --- a/src/backend/media-access-facade.cpp +++ b/src/backend/media-access-facade.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file media-access-facade.cpp + ** Implementation binding to query for a media file's properties. + ** + ** @todo this was added as a draft and mock implementation in 2008 + ** and is only used sporadic for unit tests. + */ + + #include "backend/media-access-facade.hpp" #include "lib/util.hpp" diff --git a/src/backend/media-access-facade.hpp b/src/backend/media-access-facade.hpp index 6ec32c9a7..c398f003d 100644 --- a/src/backend/media-access-facade.hpp +++ b/src/backend/media-access-facade.hpp @@ -21,6 +21,17 @@ */ +/** @file media-access-facade.hpp + ** Abstraction interface to query for a media file. + ** The corresponding service allows to discover some properties like + ** the kind and number of channels for a given file (name) ID, without + ** touching any of the technical details related to file handling. + ** + ** @todo this was added as a draft and mock implementation in 2008 + ** and is only used sporadic for unit tests. + */ + + #ifndef BACKEND_INTERFACE_MEDIA_ACCESS_FACADE_H #define BACKEND_INTERFACE_MEDIA_ACCESS_FACADE_H diff --git a/src/backend/mmap.c b/src/backend/mmap.c index 16d4f5328..fa9537ac0 100644 --- a/src/backend/mmap.c +++ b/src/backend/mmap.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file mmap.c + ** Implementation of management for memory mapped file regions + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/safeclib.h" diff --git a/src/backend/mmapcache.c b/src/backend/mmapcache.c index 4c6e6d247..9610579d6 100644 --- a/src/backend/mmapcache.c +++ b/src/backend/mmapcache.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file mmapcache.c + ** Implementation of caching for currently unused memory mapped file regions + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/safeclib.h" diff --git a/src/backend/mmapings.c b/src/backend/mmapings.c index fe648362c..8107aa177 100644 --- a/src/backend/mmapings.c +++ b/src/backend/mmapings.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file mmapings.c + ** Implementation of organisational data of memory mapped file regions + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/mutex.h" #include "lib/safeclib.h" diff --git a/src/backend/netnodefacade.cpp b/src/backend/netnodefacade.cpp index 4a8673e8b..aad613e02 100644 --- a/src/backend/netnodefacade.cpp +++ b/src/backend/netnodefacade.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file netnodefacade.cpp + ** Subsystem descriptor and configuration for a renderfarm node. + ** + ** @todo this just documents a vague plan. We won't be able to implement + ** anything of that kind for the foreseeable future as of 1/2017 + */ + + #include "backend/netnodefacade.hpp" #include "lib/depend.hpp" diff --git a/src/backend/netnodefacade.hpp b/src/backend/netnodefacade.hpp index 83b0d7be5..d4090c6b8 100644 --- a/src/backend/netnodefacade.hpp +++ b/src/backend/netnodefacade.hpp @@ -21,6 +21,14 @@ */ +/** @file netnodefacade.hpp + ** Global control interface for running Lumiera as a renderfarm node. + ** + ** @todo this just documents a vague plan. We won't be able to implement + ** anything of that kind for the foreseeable future as of 1/2017 + */ + + #ifndef BACKEND_INTERFACE_NETNODEFACADE_H #define BACKEND_INTERFACE_NETNODEFACADE_H diff --git a/src/backend/real-clock.cpp b/src/backend/real-clock.cpp index 9e758057a..aecf4d883 100644 --- a/src/backend/real-clock.cpp +++ b/src/backend/real-clock.cpp @@ -1,5 +1,5 @@ /* - Timings - timing specifications for a frame quantised data stream + RealClock - convenience front-end to access the system clock Copyright (C) Lumiera.org 2012, Hermann Vosseler @@ -21,6 +21,16 @@ * *****************************************************/ +/** @file real-clock.cpp + ** Implementation of simplified access to the current wall clock time. + ** + ** @todo just a rough draft as of 2012 / 2017 + ** @todo the idea was that the backend has elaborate knowledge about + ** timings and time progression; upper layers should thus be able + ** to fulfil their timing needs by querying the backend + */ + + #include "backend/real-clock.hpp" #include diff --git a/src/backend/resourcecollector.c b/src/backend/resourcecollector.c index 1dccc5e5e..86a8411c0 100644 --- a/src/backend/resourcecollector.c +++ b/src/backend/resourcecollector.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file resourcecollector.c + ** Implementation of a global service to manage scarce system resources + ** @todo this was a plan from 2008 and never got beyond an initial concept stage + */ + + #include "include/logging.h" #include "lib/llist.h" #include "lib/mutex.h" diff --git a/src/backend/resourcecollector.h b/src/backend/resourcecollector.h index b428bdc8c..2108335e4 100644 --- a/src/backend/resourcecollector.h +++ b/src/backend/resourcecollector.h @@ -21,6 +21,12 @@ */ +/** @file resourcecollector.h + ** A global manager for scarce system resources + ** @todo this was a plan from 2008 and never got beyond an initial concept stage + */ + + #ifndef BACKEND_RESOURCECOLLECTOR_H #define BACKEND_RESOURCECOLLECTOR_H diff --git a/src/backend/scriptrunnerfacade.cpp b/src/backend/scriptrunnerfacade.cpp index d01bb588c..888abff86 100644 --- a/src/backend/scriptrunnerfacade.cpp +++ b/src/backend/scriptrunnerfacade.cpp @@ -21,6 +21,15 @@ * *****************************************************/ +/** @file scriptrunnerfacade.cpp + ** Subsystem descriptor and configuration for a controlling and operating + ** Lumiera through bindings to a script language. + ** + ** @todo this just documents a vague plan. We won't be able to implement + ** anything of that kind for the foreseeable future as of 1/2017 + */ + + #include "backend/scriptrunnerfacade.hpp" #include "lib/depend.hpp" diff --git a/src/backend/scriptrunnerfacade.hpp b/src/backend/scriptrunnerfacade.hpp index 7ace30927..e6d46e58b 100644 --- a/src/backend/scriptrunnerfacade.hpp +++ b/src/backend/scriptrunnerfacade.hpp @@ -21,6 +21,14 @@ */ +/** @file scriptrunnerfacade.hpp + ** Global control interface for script driven operation of Lumiera. + ** + ** @todo this just documents a vague plan. We won't be able to implement + ** anything of that kind for the foreseeable future as of 1/2017 + */ + + #ifndef BACKEND_INTERFACE_SCRIPTRUNNERFACADE_H #define BACKEND_INTERFACE_SCRIPTRUNNERFACADE_H diff --git a/src/backend/thread-wrapper.hpp b/src/backend/thread-wrapper.hpp index 4bdca84a8..07da15aed 100644 --- a/src/backend/thread-wrapper.hpp +++ b/src/backend/thread-wrapper.hpp @@ -22,8 +22,22 @@ */ -#ifndef LIB_THREAD_WRAPPER_H -#define LIB_THREAD_WRAPPER_H +/** @file thread-wrapper.hpp + ** Convenience front-end for basic thread handling needs. + ** The Lumiera backend contains a dedicated low-level thread handling framework, + ** which is relevant for scheduling render activities to make best use of parallelisation + ** abilities of the given system. Typically, the upper layers should not have to deal much + ** with thread handling, yet at some point there is the need to implement a self contained + ** action running within a dedicated thread. The backend::Thread class is a wrapper to + ** represent such an parallel action conveniently and safely; together with the object + ** monitor, this allows to abstract away intricacies into self contained objects. + ** + ** @note the thread wrapper is not intended for high performance computations. + */ + + +#ifndef LIB_THREADWRAPPER_H +#define LIB_THREADWRAPPER_H #include "lib/error.hpp" @@ -280,4 +294,4 @@ namespace backend { } // namespace backend -#endif /*LIB_THREAD_WRAPPER_H*/ +#endif /*LIB_THREADWRAPPER_H*/ diff --git a/src/backend/threadpool-init.cpp b/src/backend/threadpool-init.cpp index 604a6a8ac..2634d028c 100644 --- a/src/backend/threadpool-init.cpp +++ b/src/backend/threadpool-init.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file threadpool-init.cpp + ** Implementation of automatic initialisation of the low-level thread handling framework. + */ + + #include "backend/threadpool-init.hpp" diff --git a/src/backend/threadpool-init.hpp b/src/backend/threadpool-init.hpp index 05fe29370..303ec1e00 100644 --- a/src/backend/threadpool-init.hpp +++ b/src/backend/threadpool-init.hpp @@ -22,7 +22,7 @@ */ /** @file threadpool-init.hpp - ** Automatically bring up the Threading management and Threadpool in the backend. + ** Automatically bring up the threading management and threadpool in the backend. ** This works by registering a lifecycle callback, which is activated at the start ** of main or when running the testsuite. Similarly, a shutdown hook is registered. ** diff --git a/src/backend/threadpool.c b/src/backend/threadpool.c index ea01d5e46..c00e94631 100644 --- a/src/backend/threadpool.c +++ b/src/backend/threadpool.c @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file threadpool.c + ** Implementation of a threadpool. + ** The plan is to manage the massively parallel activities by a scheduler. + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/safeclib.h" #include "backend/threadpool.h" diff --git a/src/backend/threadpool.h b/src/backend/threadpool.h index 509205ac1..4298ad74e 100644 --- a/src/backend/threadpool.h +++ b/src/backend/threadpool.h @@ -21,6 +21,11 @@ */ +/** @file threadpool.h + ** @todo development in this area is stalled since 2010 + */ + + #ifndef BACKEND_THREADPOOL_H #define BACKEND_THREADPOOL_H diff --git a/src/backend/threads.c b/src/backend/threads.c index 811c99a64..3c719eb13 100644 --- a/src/backend/threads.c +++ b/src/backend/threads.c @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file threads.c + ** Implementation of Lumiera's low-level thread handling framework + ** @todo development in this area is stalled since 2010 + */ + + #include "include/logging.h" #include "lib/safeclib.h" #include "backend/threads.h" diff --git a/src/backend/threads.h b/src/backend/threads.h index 8dc40441e..cf30bcc69 100644 --- a/src/backend/threads.h +++ b/src/backend/threads.h @@ -21,6 +21,14 @@ */ +/** @file threads.h + ** Lumiera low-level thread handling framework. + ** Exposed a limited set of operations to deal with parallelism, + ** while threads and thread creation is managed by a threadpool. + ** @todo development in this area is stalled since 2010 + */ + + #ifndef BACKEND_THREADS_H #define BACKEND_THREADS_H 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 69bb45e77..fae7f1df4 100644 --- a/src/common/advice/binding.cpp +++ b/src/common/advice/binding.cpp @@ -21,6 +21,15 @@ * *****************************************************/ +/** @file binding.cpp + ** Implementation of a binding record to represent a match between two patterns. + ** This is used for the Advice System, to record existing connections between + ** advice providers and consumers. But as such, Binding is a generic mechanism + ** and looks like it could be of wider use within the Lumiera application. + ** This is the reason why Binding got a separate implementation `cpp` file. + */ + + #include "lib/util.hpp" #include "lib/symbol.hpp" #include "common/advice/binding.hpp" @@ -57,7 +66,7 @@ namespace advice { const string matchArg = "\\(\\s*"+matchSym+"?\\s*\\)"; regex findPredicate ("\\s*"+matchSym+"("+matchArg+")?\\s*,?"); ///< \c sym(arg), groups: [symbol, parenthesis, argument symbol] - /** detect the \em arity of an predicate, as matched by #findPredicate. + /** detect the _arity_ of an predicate, as matched by #findPredicate. * Currently, we don't really parse predicate logic notation and thus we * just distinguish nullary predicates (no argument) and predicates with * one single constant argument. */ 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 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/appstate.cpp b/src/common/appstate.cpp index 9b0a459ae..2b7231265 100644 --- a/src/common/appstate.cpp +++ b/src/common/appstate.cpp @@ -1,5 +1,5 @@ /* - AppState - application initialisation and behaviour + AppState - application initialisation and behaviour Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -21,6 +21,17 @@ * *****************************************************/ +/** @file appstate.cpp + ** Implementation of the _main application object_ of Lumiera. + ** This is a service to manage some _really global_ state and to + ** organise, start and stop the ["Subsystems"](\ref subsys.hpp). + ** The AppState object provides the building blocks for the + ** `main()` function to control the global lifecycle. + ** + ** @see main.cpp + */ + + #include "lib/error.hpp" #include "include/lifecycle.h" #include "common/appstate.hpp" diff --git a/src/common/appstate.hpp b/src/common/appstate.hpp index 6f75f04ed..b68b47f29 100644 --- a/src/common/appstate.hpp +++ b/src/common/appstate.hpp @@ -1,5 +1,5 @@ /* - APPSTATE.hpp - application initialisation and behaviour + APPSTATE.hpp - application initialisation and behaviour Copyright (C) Lumiera.org 2008, Hermann Vosseler diff --git a/src/common/basic-setup.cpp b/src/common/basic-setup.cpp index 4087b17e9..16b9e2fe5 100644 --- a/src/common/basic-setup.cpp +++ b/src/common/basic-setup.cpp @@ -21,6 +21,18 @@ * *****************************************************/ +/** @file basic-setup.cpp + ** Implementation of self-configuration and bootstrap functionality. + ** This allows the application to "find its parts" at startup. + ** @note as of 2016, BasicSetup::BasicSetup(string) also reads + ** and evaluates a simple `*.ini` file to provide a + ** preliminary mechanism for application configuration. + ** This implementation is based on Boost program options + ** + ** @see searchpath.hpp + */ + + #include "common/basic-setup.hpp" #include "lib/searchpath.hpp" #include "lib/error.hpp" diff --git a/src/common/basic-setup.hpp b/src/common/basic-setup.hpp index 2f53da2bf..c018e2389 100644 --- a/src/common/basic-setup.hpp +++ b/src/common/basic-setup.hpp @@ -21,6 +21,35 @@ */ +/** @file basic-setup.hpp + ** Bootstrap and self-configuration of the application at startup. + ** The class BasicSetup represents the very basic self-configuration + ** of the application at start-up. This bootstrap is based on some + ** conventions for the application to "find its parts". + ** + ** # Motivation: why a bootstrap convention? + ** We want Lumiera to be usable _without the need of a set-up._ + ** Since the application is meant to be used in media production, users + ** often have to work in temporary and varying environments. In such a + ** situation, it is desirable just to "unzip and start" an application + ** bundle. On the other hand, obviously we want to create a nice and + ** proper, FSH compliant application, which can be packaged and installed + ** in a modern Linux distribution as first class citizen. We can fulfil + ** both demands by establishing a convention how the application can + ** discover the very basic parts necessary to start up into the `main()` + ** function and read a setup configuration. This setup configuration + ** in turn supports the definition of _search paths_ -- which then + ** allows us to deliver the application in a bundle structure which + ** both can be run from a single root folder and likewise easily + ** be mapped into FSH compliant installation folders by the + ** packager. + ** + ** @see lumiera::AppState::AppState() + ** @see main.cpp + ** + */ + + #ifndef COMMON_BASIC_SETUP_H #define COMMON_BASIC_SETUP_H diff --git a/src/common/config-interface.c b/src/common/config-interface.c index 1f0abb1a9..d71196443 100644 --- a/src/common/config-interface.c +++ b/src/common/config-interface.c @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file config-interface.c + ** A public interface to a (planned) global configuration system. + ** This is part of a drafted configuration system (2008). + ** @todo as of 2016 this code is unused and + ** likely to be replaced by a different approach. + */ + + #include "common/config-interface.h" #include "common/config.h" 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 -/** - * @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 245119686..2c6a05d0e 100644 --- a/src/common/config-wordlist.c +++ b/src/common/config-wordlist.c @@ -21,6 +21,15 @@ * *****************************************************/ +/** @file config-wordlist.c + ** Draft for a configuration system (2008). + ** Part of this is the implementation of a word list with + ** search and access functions + ** @todo as of 2016 this code is unused and + ** likely to be replaced by a different approach. + */ + + #include "include/logging.h" #include "lib/error.h" #include "lib/tmpbuf.h" diff --git a/src/common/config.c b/src/common/config.c index 15601eaf5..b08073356 100644 --- a/src/common/config.c +++ b/src/common/config.c @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file config.c + ** Implementation of a draft for application configuration from 2008. + ** @warning since 2012 it is unclear if we retain this approach + ** @todo as of 2016 this code is not used and never was + */ + + #include "include/logging.h" #include "lib/safeclib.h" #include "lib/tmpbuf.h" 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 11437ccf9..ca74e083f 100644 --- a/src/common/configentry.c +++ b/src/common/configentry.c @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file configentry.c + ** Draft for a configuration system (2008). + ** @todo as of 2016 this code is unused and + ** likely to be replaced by a different approach. + */ + + #include "lib/safeclib.h" #include "common/configentry.h" diff --git a/src/common/configentry.h b/src/common/configentry.h index 58ea04691..8a7eb0682 100644 --- a/src/common/configentry.h +++ b/src/common/configentry.h @@ -21,6 +21,13 @@ */ +/** @file configentry.h + ** Draft for a configuration system (2008). + ** @todo as of 2016 this code is unused and + ** likely to be replaced by a different approach. + */ + + #ifndef COMMON_CONFIGENTRY_H #define COMMON_CONFIGENTRY_H diff --git a/src/common/configfacade.cpp b/src/common/configfacade.cpp index 8c8d7b941..ac7500be5 100644 --- a/src/common/configfacade.cpp +++ b/src/common/configfacade.cpp @@ -21,6 +21,24 @@ * *****************************************************/ +/** @file configfacade.cpp + ** Draft for a facade to access and retrieve configuration values + ** This was created as part of a first draft towards an application + ** wide configuration system. Later (around 2012) it became clear that + ** we can not judge the requirements for such a system yet, so we deferred + ** the topic altogether. Meanwhile, this facade is sporadically used to + ** mark the necessity to retrieve some "parametrisation values". + ** + ** A preliminary implementation is backed by a `setup.ini` file, + ** located relative to the application binary. + ** + ** @todo as of 2016, this seems not to be used much, if at all. + ** The GTK-UI, which in itself is very preliminary, retrieves + ** some values from configuration, most notably the name of + ** the GTK stylesheet (`gtk-lumiera.css` is the default) + */ + + #include "include/logging.h" #include "include/lifecycle.h" #include "include/config-facade.h" 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/guifacade.cpp b/src/common/guifacade.cpp index cb94e2770..63e3e5f89 100644 --- a/src/common/guifacade.cpp +++ b/src/common/guifacade.cpp @@ -21,6 +21,16 @@ * *****************************************************/ +/** @file guifacade.cpp + ** Implementation of the GUI loader. Code generated from this + ** translation unit is linked into the core application, where it implements + ** the [Subsystem descriptor](subsys.hpp) for the _UI Subsystem._ When main() + ** activates and starts this subsystem, an instance of gui::GuiRunner will be + ** created, which causes the Lumiera UI plug-in to be loaded and a new thread + ** to be spawned, which launches the UI and performs the event loop. + */ + + #include "gui/guifacade.hpp" #include "include/gui-notification-facade.h" #include "lib/sync.hpp" diff --git a/src/common/interface-descriptor.h b/src/common/interface-descriptor.h index 7be369a17..d29e5d565 100644 --- a/src/common/interface-descriptor.h +++ b/src/common/interface-descriptor.h @@ -21,6 +21,15 @@ */ +/** @file interface-descriptor.h + ** A data record to describe interface, interface instances and plug-in + ** instances. It is used by the _interface system_ to register, open + ** and manage global extension points and separation interfaces between + ** the components of the application. + ** + */ + + #ifndef COMMON_INTERFACEDESCRIPTOR_H #define COMMON_INTERFACEDESCRIPTOR_H diff --git a/src/common/interface.h b/src/common/interface.h index 060749d11..b687e4139 100644 --- a/src/common/interface.h +++ b/src/common/interface.h @@ -30,7 +30,7 @@ ** versioned to provide forward and backward compatibility for both source and ** binary deployment of modules. ** - ** \par Overview + ** # Overview ** ** To make an interface available to code so that the code can use the ** interface, the interface needs to be declared and then defined. We provide a @@ -72,7 +72,7 @@ ** ) // Exporting from an interface ** \endcode ** - ** \par Naming and Versioning + ** # Naming and Versioning ** ** Interfaces have unique names and a major and minor version. The name and the major version ** is used to construct a C identifier for the interface, the minor version is implicitly defined diff --git a/src/common/interfaceproxy.cpp b/src/common/interfaceproxy.cpp index 1f3220f38..6128842b9 100644 --- a/src/common/interfaceproxy.cpp +++ b/src/common/interfaceproxy.cpp @@ -21,6 +21,25 @@ * *****************************************************/ +/** @file interfaceproxy.cpp + ** Implementation of C++ binding proxies on top of the (plain-C based) + ** interface system. This is an implementation facility within the application core, + ** which allows to embody just an ["interface instance handle"](\ref instancehandle.hpp), + ** in order to get RAII-style registration of interfaces and loading of plug-ins. + ** + ** A *crucial requirement* for this approach to work is, that any relevant interface + ** to be bound and exposed as C++ object needs to set up a concrete specialisation of + ** lumiera::facade::Proxy to drive instantiation of the actual binding proxy. + ** The relevant specialisations _need to be included explicitly_ into this + ** compilation unit! + ** + ** The result of this setup is that clients can just invoke `SomeInterface::facade()` + ** and thus call through proper C++ bindings with type safety and automatic + ** lifecycle management. + ** + */ + + #include "include/interfaceproxy.hpp" #include "common/instancehandle.hpp" #include "lib/error.hpp" diff --git a/src/common/option.cpp b/src/common/option.cpp index 1408ff861..ce59d986b 100644 --- a/src/common/option.cpp +++ b/src/common/option.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file option.cpp + ** Implementation of commandline argument handling, + ** based on lib Boost »program options« + */ + + #include "lib/error.hpp" #include "lib/util.hpp" #include "common/option.hpp" diff --git a/src/common/option.hpp b/src/common/option.hpp index e400702e3..e03f4e19d 100644 --- a/src/common/option.hpp +++ b/src/common/option.hpp @@ -21,6 +21,28 @@ */ +/** @file option.hpp + ** front-end for handling the commandline arguments. + ** Lumiera uses the [Boost program options library] for commandline parsing + ** and handling of a `setup.ini` file. After checking the commandline arguments + ** syntactically, the internal options representation is passed to the various + ** [Subsystems](\ref subsys.hpp) of the application. This mechanism allows + ** individual subsystems to decide if they want and need to start up at all. + ** Obviously, starting a subsystem also pulls up its prerequisites. + ** + ** The idea behind this structure is to allow operating the application in + ** various _alternative modes,_ like starting "headless" (without UI), script + ** driven or as node in a renderfarm network. + ** + ** [Boost program options library] : http://www.boost.org/doc/libs/1_55_0/doc/html/program_options.html + ** + ** @see basic-setup.hpp + ** @see lumiera::AppState + ** @see lumiera::Config + ** + */ + + #ifndef LUMIERA_OPTION_H #define LUMIERA_OPTION_H diff --git a/src/common/query/config-rules.cpp b/src/common/query/config-rules.cpp index 54826301f..ac2e6e6aa 100644 --- a/src/common/query/config-rules.cpp +++ b/src/common/query/config-rules.cpp @@ -22,6 +22,12 @@ * *****************************************************/ +/** @file config-rules.cpp + ** Implementation backend part for a configuration rules / query system. + ** @todo placeholder and mostly not implemented as of 11/2016 + */ + + #include "lib/error.hpp" #include "common/query.hpp" #include "common/config-rules.hpp" diff --git a/src/common/query/defs-manager.hpp b/src/common/query/defs-manager.hpp index ceaeab848..0f6a7134f 100644 --- a/src/common/query/defs-manager.hpp +++ b/src/common/query/defs-manager.hpp @@ -21,6 +21,76 @@ */ +/** @file defs-manager.hpp + ** Management of defaults and default rules. + ** It is one of the central ideas to shape the behaviour of Lumiera + ** not through hard wired procedures, but rather by the combination of + ** pattern elements driven by rules. A key element within this approach + ** is the notion of an *default*: Whenever some concrete calculation or + ** behaviour needs an additional element as missing link, in order to + ** reach its intrinsic goals, we (the developers) ask ourselves if the + ** for of this additional element can be derived from first principles + ** or if it is already determined by the input set driving the operation. + ** If this is _not_ the case (and the expectation is that most elements + ** are not fully determined), then we _query for an default._ This pattern + ** creates a lot of implicit extension points, which are safe to use, since + ** they are defined on a logical level. We ask for something to fulfil a + ** given contract. + ** + ** Contrast this to a system, which just has arbitrarily built-in flexibility + ** by parametrisation variables: such systems are known to be brittle, since + ** the _parameter values_ are implicitly tied to the behaviour of the operation + ** through _shared knowledge_ of implementation details. It requires both + ** "Druid knowledge" and an overall focus on the implementation mechanics to + ** adjust such parameters. In this respect, a logical query for defaults is + ** quite different, insofar it forces the implementation to respect abstractions + ** on a very fine grained level, and it allows to express the actual defaults + ** by rules which talk the language of the usage context, not the implementation + ** context. The user shall be able to define generic (logical) rules how the + ** Session should behave for the given editing project. And by combination + ** with an additional set of logical consistency rules, a resolution engine + ** can figure out what would be the right _default element_ to use at a + ** given point in the implementation. + ** + ** @note as of 2017, we are far from such a system, but it is of uttermost + ** importance that we build our implementations with this goal in mind + ** + ** # Configuration Query Interface + ** The [Defaults Manager](\ref DefsManager) exposes an interface similar to + ** a database. The intended audience of this interface is the writer of + ** low-level implementation code. This facade interface is meant to create + ** a more familiar front-end to an essentially logic and rules driven + ** configuration system. And, as an additional benefit, it can be implemented + ** just by a glorified table lookup. Which indeed is what we do until the more + ** elaborate rules based system is in place. + ** + ** An implementation process in need for some missing link typically knows the + ** _type of that missing element._ Which means, this type is possibly an abstract + ** type and defines the contract any solution has to fulfil. Thus, the usage context + ** can just demand "give me a suitable XYZ!". In practice, there are several flavours + ** to this interaction, each of which is expressed by a dedicated method on the + ** DefsManager facade interface: + ** - we can just *retrieve* a suitable solution element, no questions asked. + ** - we can *query* for a suitable solution, while limiting the search to what + ** is already known and defined. This entails the possibility that there is + ** no known solution yet. + ** - we can *demand to fabricate* a suitable solution element. Such a call might + ** still deliver something already fabricated, but the emphasis is on the + ** "make it so" demand. + ** - we can *provide and associate* a solution element we created ourselves, + ** to be available from now on, and associated with a given query. Even + ** this call implicates the necessity for the query to be fulfilled by + ** the given element, which, as a consequence includes the possibility + ** of failure. + ** - for sake of completeness, we can also require a specific element to + ** be purged from knowledge + ** + ** @see DefsManager_test + ** @see DefsManagerImpl_test + ** + */ + + #ifndef LUMIERA_QUERY_DEFS_MANAGER_H #define LUMIERA_QUERY_DEFS_MANAGER_H diff --git a/src/common/query/defs-registry.hpp b/src/common/query/defs-registry.hpp index 41e3a91a8..dbc9cbde7 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 f6bdbbf60..358414a5f 100644 --- a/src/common/query/query-resolver.cpp +++ b/src/common/query/query-resolver.cpp @@ -21,6 +21,18 @@ * *****************************************************/ +/** @file query-resolver.cpp + ** implementation of a framework to query and discover elements + ** based on logical rules. This framework builds on the notion of + ** possibly having several QueryResolver facilities to handle various + ** kinds of queries in an uniform way. To reflect that design, the + ** implementation is built round a DispatcherTable to forward requests + ** to concrete entities implementing the QueryResolver interface. The + ** actual query resolution mechanism is thus not part of the framework. + ** + */ + + #include "lib/multifact.hpp" #include "common/query/query-resolver.hpp" @@ -97,7 +109,7 @@ namespace lumiera { REQUIRE (!dispatcher_->empty(), "attempt to issue a query without having installed any resolver (yet)"); if (!canHandle (query)) - throw lumiera::error::Invalid ("unable to resolve this kind of query"); ////TICKET #197 + throw lumiera::error::Invalid ("unable to resolve this kind of query"); //////////////////////////////////TICKET #197 return dispatcher_->handle(query); } diff --git a/src/common/query/query-resolver.hpp b/src/common/query/query-resolver.hpp index 39e8dea4f..1db99aa73 100644 --- a/src/common/query/query-resolver.hpp +++ b/src/common/query/query-resolver.hpp @@ -21,6 +21,17 @@ */ +/** @file query-resolver.hpp + ** framework and to resolve logical queries. + ** This header defines a family of interfaces and classes + ** to integrate resolution of logical, rules based queries into generic + ** implementation code. The concrete facility actually to resolve such queries + ** is abstracted away as QueryResolver. A prominent usage example is the session, + ** which allows to query for elements "somewhere within the model" + ** + */ + + #ifndef LUMIERA_QUERY_RESOLVER_H #define LUMIERA_QUERY_RESOLVER_H diff --git a/src/common/subsys.cpp b/src/common/subsys.cpp index 10d419b4f..287dfcfd4 100644 --- a/src/common/subsys.cpp +++ b/src/common/subsys.cpp @@ -21,6 +21,19 @@ * *****************************************************/ +/** @file subsys.cpp + ** Implementation details of a »subsystem descriptor«. + ** The application is split into various such subsystems, + ** which are prompted by main() to start/stop. + ** + ** @see subsystem-runner.hpp + ** @see lumiera::AppState + ** @see facade.cpp + ** @see main.cpp + ** + */ + + #include "common/subsys.hpp" diff --git a/src/common/subsystem-runner.hpp b/src/common/subsystem-runner.hpp index 92d5800de..c3fbfba8b 100644 --- a/src/common/subsystem-runner.hpp +++ b/src/common/subsystem-runner.hpp @@ -21,6 +21,28 @@ */ +/** @file subsystem-runner.hpp + ** Manage execution of the independend [Subsystems](\ref subsys.hpp) + ** of the Lumiera application. The SubsystemRunner is used by + ** lumiera::AppState::init() for actually "performing" the various subsystems, + ** as defined by their [Subsystem descriptors](\ref lumiera::Subsys). Together + ** these parts define the lifecycle protocol. + ** + ** @remark While this facility is still pretty much the first implementation draft + ** from 2008, it fulfilled our needs to express simple dependencies and to + ** conduct a controlled shutdown in case of fatal problems. The operations + ** protocol implied by this implementation might be somewhat brittle and + ** creates strong ties to implementation details, like the fine points + ** of thread handling and locking. If we ever consider to build an + ** improved subsystem runner, we should care to include the + ** full set of lifecycle callbacks, similar to a + ** two phase commit in databases. + ** + ** @see SubsystemRunner_test + ** + */ + + #ifndef LUMIERA_SUBSYSTEMRUNNER_H #define LUMIERA_SUBSYSTEMRUNNER_H diff --git a/src/gui/ctrl/playback-controller.cpp b/src/gui/ctrl/playback-controller.cpp index 8bba5ae21..9152f1943 100644 --- a/src/gui/ctrl/playback-controller.cpp +++ b/src/gui/ctrl/playback-controller.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file playback-controller.cpp + ** Implementation parts of PlaybackController. + ** @warning this is preliminary code and will be reworked, once + ** we're able to connect to actual playback processes + ** performed by the render engine. + */ + + #include "gui/ctrl/playback-controller.hpp" #include "gui/display-service.hpp" #include "lib/error.hpp" diff --git a/src/gui/dialog/dialog.hpp b/src/gui/dialog/dialog.hpp index 318490624..4137c167d 100644 --- a/src/gui/dialog/dialog.hpp +++ b/src/gui/dialog/dialog.hpp @@ -21,6 +21,11 @@ */ +/** @file dialog.hpp + ** Global constants and definitions for dialogs. + */ + + #ifndef GUI_DIALOG_DIALOG_H #define GUI_DIALOG_DIALOG_H diff --git a/src/gui/dialog/name-chooser.cpp b/src/gui/dialog/name-chooser.cpp index 4de2596df..c8a48c023 100644 --- a/src/gui/dialog/name-chooser.cpp +++ b/src/gui/dialog/name-chooser.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file name-chooser.cpp + ** Implementation details of NameChooser, + ** a dialog to enter a name string. + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/dialog/name-chooser.hpp" #include "gui/dialog/dialog.hpp" diff --git a/src/gui/dialog/name-chooser.hpp b/src/gui/dialog/name-chooser.hpp index 4e202b0be..efb98e5ee 100644 --- a/src/gui/dialog/name-chooser.hpp +++ b/src/gui/dialog/name-chooser.hpp @@ -21,6 +21,11 @@ */ +/** @file name-chooser.hpp + ** Dialog to enter a string name. + */ + + #ifndef GUI_DIALOG_NAME_CHOOSER_H #define GUI_DIALOG_NAME_CHOOSER_H diff --git a/src/gui/dialog/preferences-dialog.hpp b/src/gui/dialog/preferences-dialog.hpp index f508ee6cd..71df694d7 100644 --- a/src/gui/dialog/preferences-dialog.hpp +++ b/src/gui/dialog/preferences-dialog.hpp @@ -21,6 +21,14 @@ */ +/** @file preferences-dialog.hpp + ** Dialog to manage application preferences. + ** @todo as of 2016, this is more of a place-holder, since we also + ** do not have decided on the implementation approach for + ** application preferences in general. + */ + + #ifndef GUI_DIALOG_PREFERENCES_DIALOG_H #define GUI_DIALOG_PREFERENCES_DIALOG_H diff --git a/src/gui/dialog/render.cpp b/src/gui/dialog/render.cpp index cfe706a67..f775057c7 100644 --- a/src/gui/dialog/render.cpp +++ b/src/gui/dialog/render.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file render.cpp + ** Implementation of gui:dialog::Render, which is a Dialog + ** to set up a renter process and define output name and format. + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/dialog/render.hpp" diff --git a/src/gui/dialog/render.hpp b/src/gui/dialog/render.hpp index 5f105b31c..e35d71851 100644 --- a/src/gui/dialog/render.hpp +++ b/src/gui/dialog/render.hpp @@ -21,7 +21,7 @@ */ /** @file render.hpp - ** definition of the render output dialog + ** Dialog to set up a renter process and define output name and format. ** */ diff --git a/src/gui/display-interface-proxy.hpp b/src/gui/display-interface-proxy.hpp index 49ffbf36e..2b0130a37 100644 --- a/src/gui/display-interface-proxy.hpp +++ b/src/gui/display-interface-proxy.hpp @@ -40,6 +40,7 @@ /* ==================== gui::Display ====================================== */ #include "include/display-facade.h" +#include "include/interfaceproxy.hpp" namespace lumiera { diff --git a/src/gui/display-service.cpp b/src/gui/display-service.cpp index 8aedac1bc..4bfadbb60 100644 --- a/src/gui/display-service.cpp +++ b/src/gui/display-service.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file display-service.cpp + ** Implementation of _Displayer Service,_ exposed as a public interface. + ** This service allows to set up _display slots,_ which can be handed over + ** to client code in the course of the play process for outputting frames. + */ + + #include "gui/display-service.hpp" extern "C" { diff --git a/src/gui/display-service.hpp b/src/gui/display-service.hpp index 78463d1c3..e25446432 100644 --- a/src/gui/display-service.hpp +++ b/src/gui/display-service.hpp @@ -116,7 +116,7 @@ namespace gui { * the Lumiera Interface/Plugin system and creates * a forwarding proxy within the application core to * route calls through this interface. - * \par + * * In addition to the Display interface, this class * implements an additional service for the GUI, * allowing actually to set up display slots, which diff --git a/src/gui/gtk-lumiera.cpp b/src/gui/gtk-lumiera.cpp index da3f4ab2b..254f6b9ef 100644 --- a/src/gui/gtk-lumiera.cpp +++ b/src/gui/gtk-lumiera.cpp @@ -21,6 +21,10 @@ * *****************************************************/ +/** @file gtk-lumiera.cpp + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/ctrl/ui-manager.hpp" #include "gui/ui-bus.hpp" diff --git a/src/gui/guifacade.hpp b/src/gui/guifacade.hpp index 1f44920ee..b26288219 100644 --- a/src/gui/guifacade.hpp +++ b/src/gui/guifacade.hpp @@ -25,7 +25,7 @@ ** lower layers of Lumiera. While part of the public interface of the Lumiera GUI, ** the implementation of this facility is part of the core application (and not ** contained within the GUI dynamic module), because it's job is to load and - ** activate this module and to startup the GUI. + ** activate this module as plug-in and to startup the GUI. ** ** @see lumiera::AppState ** @see lumiera::Option diff --git a/src/gui/model/clip-track.cpp b/src/gui/model/clip-track.cpp index aad942e0c..3bfb48737 100644 --- a/src/gui/model/clip-track.cpp +++ b/src/gui/model/clip-track.cpp @@ -20,6 +20,13 @@ * *****************************************************/ + +/** @file clip-track.cpp + ** Preliminary UI-model: Implementation of timeline track model object. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + */ + #include "clip-track.hpp" #include "clip.hpp" diff --git a/src/gui/model/clip-track.hpp b/src/gui/model/clip-track.hpp index 9ebd049f0..4441cb16a 100644 --- a/src/gui/model/clip-track.hpp +++ b/src/gui/model/clip-track.hpp @@ -21,9 +21,10 @@ */ /** - * @file model/clip-track.hpp - * This file contains the definition of timeline track objects which - * contain clips. + ** @file model/clip-track.hpp + ** Preliminary UI-model: Definition of timeline track objects which contain clips. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. */ diff --git a/src/gui/model/clip.cpp b/src/gui/model/clip.cpp index f78e2c2af..ee6dead8d 100644 --- a/src/gui/model/clip.cpp +++ b/src/gui/model/clip.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file clip.cpp + ** Preliminary UI-model: implementation of a Clip object as placeholder to + ** base the GUI implementation on. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + */ + + #include "gui/model/clip.hpp" #include "lib/time/mutation.hpp" diff --git a/src/gui/model/clip.hpp b/src/gui/model/clip.hpp index 134680e95..71cd15f2f 100644 --- a/src/gui/model/clip.hpp +++ b/src/gui/model/clip.hpp @@ -21,8 +21,10 @@ */ /** @file model/clip.hpp - ** This file defines a Proxy Clip object to base the GUI implementation on. + ** Preliminary UI-model: a Proxy Clip object to base the GUI implementation on. ** Later this Clip object will be connected to the underlying model in Proc-Layer. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. */ #ifndef GUI_MODEL_CLIP_H diff --git a/src/gui/model/group-track.cpp b/src/gui/model/group-track.cpp index 067821d82..f5fb8415c 100644 --- a/src/gui/model/group-track.cpp +++ b/src/gui/model/group-track.cpp @@ -20,6 +20,14 @@ * *****************************************************/ + +/** @file group-track.cpp + ** Preliminary UI-model: Implementation for the group track timeline objects. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** @deprecated the existing timeline implementation will be completely rewritten + */ + #include "group-track.hpp" namespace gui { diff --git a/src/gui/model/group-track.hpp b/src/gui/model/group-track.hpp index 77ccc9a5e..11185a571 100644 --- a/src/gui/model/group-track.hpp +++ b/src/gui/model/group-track.hpp @@ -21,7 +21,10 @@ */ /** @file widget/timeline/group-track.hpp - ** This file contains the definition of group track timeline objects + ** Preliminary UI-model: Definition of group track timeline objects. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** @deprecated the existing timeline implementation will be completely rewritten */ @@ -36,6 +39,7 @@ namespace model { /** * A class representation of a grouping of tracks. + * @deprecated the existing timeline implementation will be rewritten */ class GroupTrack : public ParentTrack { diff --git a/src/gui/model/parent-track.cpp b/src/gui/model/parent-track.cpp index cfa4a95ff..60b509ac2 100644 --- a/src/gui/model/parent-track.cpp +++ b/src/gui/model/parent-track.cpp @@ -20,6 +20,14 @@ * *****************************************************/ + +/** @file parent-track.cpp + ** Preliminary UI-model: Implementation of ParentTrack. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** @deprecated the existing timeline implementation will be completely rewritten + */ + #include "parent-track.hpp" #include diff --git a/src/gui/model/parent-track.hpp b/src/gui/model/parent-track.hpp index cb1228463..c21110803 100644 --- a/src/gui/model/parent-track.hpp +++ b/src/gui/model/parent-track.hpp @@ -20,9 +20,12 @@ */ /** @file parent-track.hpp - ** This file contains the definition of ParentTrack, a class which + ** Preliminary UI-model: Definition of ParentTrack, a class which ** represents a base functionality for tracks and sequences which - ** are also track parents. This class wraps proc layer data + ** are also track parents. This class was intended to wraps proc layer data. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** @deprecated the existing timeline implementation will be completely rewritten */ #ifndef PARENT_TRACK_HPP @@ -35,8 +38,8 @@ namespace gui { namespace model { /** - * ParentTrack is the abstract base class of all tracks that can parent - * children. + * ParentTrack is the abstract base class of all tracks that can parent children. + * @deprecated the existing timeline implementation will be rewritten */ class ParentTrack : public Track, diff --git a/src/gui/model/project.cpp b/src/gui/model/project.cpp index 78ebc0e8e..d33f02247 100644 --- a/src/gui/model/project.cpp +++ b/src/gui/model/project.cpp @@ -21,6 +21,15 @@ * *****************************************************/ +/** @file project.cpp + ** Preliminary UI-model: Implementation of Project, a class which + ** stores project data, and wraps proc layer data. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** + */ + + #include "gui/model/project.hpp" #include "gui/model/sequence.hpp" diff --git a/src/gui/model/project.hpp b/src/gui/model/project.hpp index 363c73544..466986aac 100644 --- a/src/gui/model/project.hpp +++ b/src/gui/model/project.hpp @@ -21,8 +21,10 @@ */ /** @file project.hpp - ** This file contains the definition of Project, a class which + ** Preliminary UI-model: Definition of Project, a class which ** stores project data, and wraps proc layer data. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. ** ** @todo this solution was used to build the first outline of the UI. ** It needs to be reshaped into a connector to Proc-Layer ///////////////TICKET #959 diff --git a/src/gui/model/sequence.cpp b/src/gui/model/sequence.cpp index 830420c83..37ba5c46e 100644 --- a/src/gui/model/sequence.cpp +++ b/src/gui/model/sequence.cpp @@ -20,6 +20,13 @@ * *****************************************************/ + +/** @file sequence.cpp + ** Preliminary UI-model: implementation of an editable sequence. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + */ + #include "gui/model/sequence.hpp" #include "include/logging.h" diff --git a/src/gui/model/sequence.hpp b/src/gui/model/sequence.hpp index aae7873ab..e43209340 100644 --- a/src/gui/model/sequence.hpp +++ b/src/gui/model/sequence.hpp @@ -21,10 +21,12 @@ */ /** @file sequence.hpp - ** The GUI-Model representation of an editable sequence. - ** @todo Currently (1/2014) this is a dummy placeholder, but later on - ** the GUI-Model entities will be connected to the Session model - ** through the use of PlacementRef + ** 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. + ** + ** @todo Currently (1/2014) this is a dummy placeholder, intention is + ** to connect GUI-Model entities to the Session model eventually. */ diff --git a/src/gui/model/track.cpp b/src/gui/model/track.cpp index 35f0c2473..ed3190134 100644 --- a/src/gui/model/track.cpp +++ b/src/gui/model/track.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file track.cpp + ** Preliminary UI-model: Implementation for the track timeline objects. + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** @deprecated the existing timeline implementation will be completely rewritten + */ + + #include "gui/model/track.hpp" #include "gui/model/parent-track.hpp" diff --git a/src/gui/model/track.hpp b/src/gui/model/track.hpp index 845c6f234..b204cb07c 100644 --- a/src/gui/model/track.hpp +++ b/src/gui/model/track.hpp @@ -20,8 +20,11 @@ */ /** @file track.hpp - ** This file contains the definition of Track, a class which + ** Preliminary UI-model: Definition of Track, a class which ** represents a track, and wraps proc layer data + ** @warning as of 2016 this UI model is known to be a temporary workaround + ** and will be replaced in entirety by UI-Bus and diff framework. + ** @deprecated the existing timeline implementation will be completely rewritten */ diff --git a/src/gui/notification-interface-proxy.hpp b/src/gui/notification-interface-proxy.hpp index b4314953c..d7ca62e3d 100644 --- a/src/gui/notification-interface-proxy.hpp +++ b/src/gui/notification-interface-proxy.hpp @@ -37,8 +37,9 @@ /* ==================== GuiNotification =================================== */ - + #include "include/gui-notification-facade.h" +#include "include/interfaceproxy.hpp" namespace gui { diff --git a/src/gui/notification-service.cpp b/src/gui/notification-service.cpp index e6f37eb38..4c6007eb4 100644 --- a/src/gui/notification-service.cpp +++ b/src/gui/notification-service.cpp @@ -29,6 +29,11 @@ ** */ +/** @file notification-service.cpp + ** @todo write documentation for the notification service + */ + + #include "gui/notification-service.hpp" #include "include/logging.h" #include "lib/depend.hpp" diff --git a/src/gui/output/displayer.cpp b/src/gui/output/displayer.cpp index ca1537913..d773762bb 100644 --- a/src/gui/output/displayer.cpp +++ b/src/gui/output/displayer.cpp @@ -23,6 +23,18 @@ * *****************************************************/ +/** @file displayer.cpp + ** Implementation of a displayer object, intended for creating + ** a video display in the UI. This class was created as part of + ** an initial draft of the user interface. + ** @warning as of 2016 it is not clear, if this code will be + ** evolved into the actual display facility, or be + ** replaced and rewritten, when we're about to + ** create a functional video display connected + ** to the render engine. + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/output/displayer.hpp" #include "gui/output/xvdisplayer.hpp" diff --git a/src/gui/output/displayer.hpp b/src/gui/output/displayer.hpp index 157dc4151..6f02d395c 100644 --- a/src/gui/output/displayer.hpp +++ b/src/gui/output/displayer.hpp @@ -24,7 +24,11 @@ /** @file displayer.hpp ** The Displayer serves as base of all video display implementations - ** + ** @warning as of 2016 it is not clear, if this code will be + ** evolved into the actual display facility, or be + ** replaced and rewritten, when we're about to + ** create a functional video display connected + ** to the render engine. */ diff --git a/src/gui/output/gdkdisplayer.cpp b/src/gui/output/gdkdisplayer.cpp index f655f68ff..f27d6f527 100644 --- a/src/gui/output/gdkdisplayer.cpp +++ b/src/gui/output/gdkdisplayer.cpp @@ -23,6 +23,13 @@ * *****************************************************/ +/** @file gdkdisplayer.cpp + ** Dysfunctional implementation code, formerly used to + ** create a video display based on GDK + ** @deprecated obsolete since GTK-3 + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/output/gdkdisplayer.hpp" diff --git a/src/gui/output/xvdisplayer.cpp b/src/gui/output/xvdisplayer.cpp index eacb64de7..b76dc9755 100644 --- a/src/gui/output/xvdisplayer.cpp +++ b/src/gui/output/xvdisplayer.cpp @@ -23,6 +23,16 @@ * *****************************************************/ +/** @file xvdisplayer.cpp + ** Implementation of video output via XVideo + ** @warning as of 2016 it is not clear, if this code will be + ** evolved into the actual display facility, or be + ** replaced and rewritten, when we're about to + ** create a functional video display connected + ** to the render engine. + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/output/xvdisplayer.hpp" #include "include/logging.h" diff --git a/src/gui/output/xvdisplayer.hpp b/src/gui/output/xvdisplayer.hpp index 8e87b4438..3b7af42d8 100644 --- a/src/gui/output/xvdisplayer.hpp +++ b/src/gui/output/xvdisplayer.hpp @@ -25,7 +25,11 @@ /** @file xvdisplayer.hpp ** Implementation of video output via XVideo - ** + ** @warning as of 2016 it is not clear, if this code will be + ** evolved into the actual display facility, or be + ** replaced and rewritten, when we're about to + ** create a functional video display connected + ** to the render engine. ** @see displayer.hpp */ diff --git a/src/gui/panel/assets-panel.cpp b/src/gui/panel/assets-panel.cpp index f15baada0..dc363d5d7 100644 --- a/src/gui/panel/assets-panel.cpp +++ b/src/gui/panel/assets-panel.cpp @@ -20,6 +20,11 @@ * *****************************************************/ + +/** @file assets-panel.cpp + ** Implementation of a (dockable) panel to organise the assets of a project. + */ + #include "gui/gtk-lumiera.hpp" #include "gui/panel/assets-panel.hpp" diff --git a/src/gui/panel/assets-panel.hpp b/src/gui/panel/assets-panel.hpp index acd65ef53..9e7afa2d1 100644 --- a/src/gui/panel/assets-panel.hpp +++ b/src/gui/panel/assets-panel.hpp @@ -21,6 +21,17 @@ */ +/** @file assets-panel.hpp + ** A (dockable) panel to organise the assets of a project. + ** Assets are descriptor objects maintained within the Session model. + ** They are used to represent + ** - media and clips + ** - processors, effects etc. + ** - structural elements like timeline, tracks, sequences etc. + ** - metadata descriptors + */ + + #ifndef GUI_PANEL_ASSETS_PANEL_H #define GUI_PANEL_ASSETS_PANEL_H diff --git a/src/gui/panel/panel.cpp b/src/gui/panel/panel.cpp index ba8b5bdc6..01aa02bba 100644 --- a/src/gui/panel/panel.cpp +++ b/src/gui/panel/panel.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file panel.cpp + ** Implementation base for all dockable panels + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/panel/panel.hpp" #include "gui/workspace/panel-manager.hpp" diff --git a/src/gui/panel/panel.hpp b/src/gui/panel/panel.hpp index 0b7b85768..83d725ee4 100644 --- a/src/gui/panel/panel.hpp +++ b/src/gui/panel/panel.hpp @@ -21,6 +21,11 @@ */ +/** @file panel.hpp + ** Base class and interface for all dockable panels + */ + + #ifndef GUI_PANEL_PANEL_H #define GUI_PANEL_PANEL_H diff --git a/src/gui/panel/timeline-panel.cpp b/src/gui/panel/timeline-panel.cpp index a637c686c..e98739d42 100644 --- a/src/gui/panel/timeline-panel.cpp +++ b/src/gui/panel/timeline-panel.cpp @@ -22,7 +22,7 @@ /** @file timeline-panel.cpp - ** Implementation of dockable timeline container. + ** Implementation of the dockable panel to hold the main timeline display. ** ** @todo as of 10/2016 this is WIP-WIP-WIP : canvas widgets experiment ** @todo build a new timeline widget, connected to the UI-Bus diff --git a/src/gui/panel/viewer-panel.cpp b/src/gui/panel/viewer-panel.cpp index 16bf01e63..ca751f560 100644 --- a/src/gui/panel/viewer-panel.cpp +++ b/src/gui/panel/viewer-panel.cpp @@ -20,6 +20,11 @@ * *****************************************************/ + +/** @file viewer-panel.cpp + ** Implementation of a dockable panel to hold the video viewers + */ + #include "gui/gtk-lumiera.hpp" #include "gui/panel/viewer-panel.hpp" diff --git a/src/gui/panel/viewer-panel.hpp b/src/gui/panel/viewer-panel.hpp index f26b1c5a9..f45d94b4f 100644 --- a/src/gui/panel/viewer-panel.hpp +++ b/src/gui/panel/viewer-panel.hpp @@ -21,7 +21,7 @@ */ /** @file viewer-panel.hpp - ** This file contains the definition of the viewer panel + ** Definition of a dockable panel to hold the video viewers */ diff --git a/src/gui/util/cairo-util.cpp b/src/gui/util/cairo-util.cpp index 44fd395ec..4165c6317 100644 --- a/src/gui/util/cairo-util.cpp +++ b/src/gui/util/cairo-util.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file cairo-util.cpp + ** Implementation of helper functions to support working with lib Cairo + */ + + #include "gui/util/cairo-util.hpp" namespace gui { diff --git a/src/gui/util/cairo-util.hpp b/src/gui/util/cairo-util.hpp index dcd30df69..788c5bc06 100644 --- a/src/gui/util/cairo-util.hpp +++ b/src/gui/util/cairo-util.hpp @@ -20,6 +20,12 @@ * *****************************************************/ + +/** @file cairo-util.hpp + ** Utility functions for working with elements from the Cairo + ** vector drawing library. + */ + #include #ifndef GUI_UTIL_CAIRO_H diff --git a/src/gui/util/rectangle.cpp b/src/gui/util/rectangle.cpp index 6ae7f34ee..9a1dfcf0f 100644 --- a/src/gui/util/rectangle.cpp +++ b/src/gui/util/rectangle.cpp @@ -20,6 +20,11 @@ * *****************************************************/ + +/** @file rectangle.cpp + ** Implementation of functions to work with rectangular screen ranges + */ + #include "gui/util/rectangle.hpp" #include diff --git a/src/gui/util/rectangle.hpp b/src/gui/util/rectangle.hpp index ef8827eed..3fd168612 100644 --- a/src/gui/util/rectangle.hpp +++ b/src/gui/util/rectangle.hpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file rectangle.hpp + ** Helper functions to work with rectangular screen ranges + */ + + #ifndef GUI_UTIL_RECTANGLE_H #define GUI_UTIL_RECTANGLE_H diff --git a/src/gui/widget/button-bar.cpp b/src/gui/widget/button-bar.cpp index 5d354eed1..2ac8b1195 100644 --- a/src/gui/widget/button-bar.cpp +++ b/src/gui/widget/button-bar.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file button-bar.cpp + ** Implementation of a toolbar with buttons for use in dialogs. + */ + + #include "gui/widget/button-bar.hpp" #include "include/logging.h" diff --git a/src/gui/widget/button-bar.hpp b/src/gui/widget/button-bar.hpp index 8af874eb4..b83f0e486 100644 --- a/src/gui/widget/button-bar.hpp +++ b/src/gui/widget/button-bar.hpp @@ -21,6 +21,11 @@ */ +/** @file button-bar.hpp + ** A toolbar widget for use in dialogs. + */ + + #ifndef GUI_WIDGET_BUTTON_BAR_H #define GUI_WIDGET_BUTTON_BAR_H diff --git a/src/gui/widget/menu-button.cpp b/src/gui/widget/menu-button.cpp index e4897d552..d4ebd14c7 100644 --- a/src/gui/widget/menu-button.cpp +++ b/src/gui/widget/menu-button.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file menu-button.cpp + ** Implementation of the MenuButton widget, to display a menu when clicked. + */ + + #include "gui/widget/menu-button.hpp" diff --git a/src/gui/widget/menu-button.hpp b/src/gui/widget/menu-button.hpp index 67768dbe7..11092331f 100644 --- a/src/gui/widget/menu-button.hpp +++ b/src/gui/widget/menu-button.hpp @@ -21,6 +21,11 @@ */ +/** @file menu-button.hpp + ** A button widget that displays a menu when clicked. + */ + + #ifndef GUI_WIDGET_MENU_BUTTON_H #define GUI_WIDGET_MENU_BUTTON_H diff --git a/src/gui/widget/mini-button.hpp b/src/gui/widget/mini-button.hpp index 6b2775b7f..6ddcbe36b 100644 --- a/src/gui/widget/mini-button.hpp +++ b/src/gui/widget/mini-button.hpp @@ -21,6 +21,11 @@ */ +/** @file mini-button.hpp + ** Adapter to wrap button widgets intended to serve as tool buttons + */ + + #ifndef GUI_WIDGET_MINI_BUTTON_H #define GUI_WIDGET_MINI_BUTTON_H diff --git a/src/gui/widget/panel-bar.cpp b/src/gui/widget/panel-bar.cpp index f77c69dad..003aadd00 100644 --- a/src/gui/widget/panel-bar.cpp +++ b/src/gui/widget/panel-bar.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file panel-bar.cpp + ** Implementation of a custom container widget to place toolbar buttons + ** into the active docking header area of GDL docking panels. + */ + + #include "gui/widget/panel-bar.hpp" #include "gui/workspace/workspace-window.hpp" #include "gui/workspace/panel-manager.hpp" diff --git a/src/gui/widget/timecode-widget.cpp b/src/gui/widget/timecode-widget.cpp index e4f1b1d83..a99b4a466 100644 --- a/src/gui/widget/timecode-widget.cpp +++ b/src/gui/widget/timecode-widget.cpp @@ -24,6 +24,12 @@ * *****************************************************/ +/** @file timecode-widget.cpp + ** Widget for timecode display and input. + ** Ported and adapted from the Ardour DAW + */ + + #include "gui/widget/timecode-widget.hpp" #include "lib/time/diagnostics.hpp" ////////////TODO: temporary solution to get H:M:S components. Use TimeCode instead! diff --git a/src/gui/widget/timecode-widget.hpp b/src/gui/widget/timecode-widget.hpp index a896dc40a..3ff2fefe6 100644 --- a/src/gui/widget/timecode-widget.hpp +++ b/src/gui/widget/timecode-widget.hpp @@ -24,6 +24,14 @@ */ +/** @file timecode-widget.hpp + ** Widget for timecode display and input. + ** Ported and adapted from the Ardour DAW. + ** @todo needs extensive rework to get smooth integration + ** with Lumiera's timecode handling functions + */ + + #ifndef GUI_WIDGET_TIMECODE_WIDGET_H #define GUI_WIDGET_TIMECODE_WIDGET_H @@ -50,7 +58,7 @@ namespace widget { /** - * Widget for timecode imput and display. + * Widget for timecode input and display. * Adapted implementation from the Ardour DAW */ class TimeCode diff --git a/src/gui/widget/timeline/basic-draw-strategy.hpp b/src/gui/widget/timeline/basic-draw-strategy.hpp index 38bdeb305..571cf1b26 100644 --- a/src/gui/widget/timeline/basic-draw-strategy.hpp +++ b/src/gui/widget/timeline/basic-draw-strategy.hpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file basic-draw-strategy.hpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_BASIC_DRAW_STRATEGY_H #define GUI_WIDGET_TIMELINE_BASIC_DRAW_STRATEGY_H diff --git a/src/gui/widget/timeline/draw-strategy.cpp b/src/gui/widget/timeline/draw-strategy.cpp index 5a9f00d6b..b0730989c 100644 --- a/src/gui/widget/timeline/draw-strategy.cpp +++ b/src/gui/widget/timeline/draw-strategy.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file draw-strategy.cpp + ** @deprecated very likely to be completely rewritten. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/basic-draw-strategy.hpp" namespace gui { diff --git a/src/gui/widget/timeline/draw-strategy.hpp b/src/gui/widget/timeline/draw-strategy.hpp index 9dc8909ff..2fe308d5e 100644 --- a/src/gui/widget/timeline/draw-strategy.hpp +++ b/src/gui/widget/timeline/draw-strategy.hpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file draw-strategy.hpp + ** Strategy interface for drawing timeline entities. This is part of the + ** first implementation draft of the timeline display. + ** @deprecated very likely to be completely rewritten. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_DRAW_STRATEGY_HPP #define GUI_WIDGET_TIMELINE_DRAW_STRATEGY_HPP diff --git a/src/gui/widget/timeline/timeline-arrow-tool.cpp b/src/gui/widget/timeline/timeline-arrow-tool.cpp index 5dd60848e..a64cff2fe 100644 --- a/src/gui/widget/timeline/timeline-arrow-tool.cpp +++ b/src/gui/widget/timeline/timeline-arrow-tool.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-arrow-tool.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-arrow-tool.hpp" namespace gui { diff --git a/src/gui/widget/timeline/timeline-arrow-tool.hpp b/src/gui/widget/timeline/timeline-arrow-tool.hpp index 5bbfefaaf..cc95695d9 100644 --- a/src/gui/widget/timeline/timeline-arrow-tool.hpp +++ b/src/gui/widget/timeline/timeline-arrow-tool.hpp @@ -22,6 +22,7 @@ /** @file timeline-arrow-tool.hpp ** This file contains the definition of the arrow tool class + ** @warning as of 2016 the entire timeline display is planned to be reworked */ #ifndef GUI_WIDGET_TIMELINE_ARROW_TOOL_H diff --git a/src/gui/widget/timeline/timeline-body.cpp b/src/gui/widget/timeline/timeline-body.cpp index 3d1223fc5..35696ad1a 100644 --- a/src/gui/widget/timeline/timeline-body.cpp +++ b/src/gui/widget/timeline/timeline-body.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-body.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-body.hpp" #include "gui/widget/timeline-widget.hpp" #include "gui/workspace/style-manager.hpp" diff --git a/src/gui/widget/timeline/timeline-body.hpp b/src/gui/widget/timeline/timeline-body.hpp index a2ef4e29f..0766c1a83 100644 --- a/src/gui/widget/timeline/timeline-body.hpp +++ b/src/gui/widget/timeline/timeline-body.hpp @@ -22,6 +22,7 @@ /** @file timeline-body.hpp ** This file contains the definition of timeline body widget + ** @warning as of 2016 the entire timeline display is planned to be reworked */ #ifndef GUI_WIDGET_TIMELINE_BODY_H diff --git a/src/gui/widget/timeline/timeline-clip-track.cpp b/src/gui/widget/timeline/timeline-clip-track.cpp index 22c6b7324..6b169c5b9 100644 --- a/src/gui/widget/timeline/timeline-clip-track.cpp +++ b/src/gui/widget/timeline/timeline-clip-track.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-clip-track.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-clip.hpp" #include "gui/widget/timeline/timeline-clip-track.hpp" #include "gui/widget/timeline/timeline-view-window.hpp" diff --git a/src/gui/widget/timeline/timeline-clip.cpp b/src/gui/widget/timeline/timeline-clip.cpp index c8ee93bd3..38ee1339a 100644 --- a/src/gui/widget/timeline/timeline-clip.cpp +++ b/src/gui/widget/timeline/timeline-clip.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-clip.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-clip.hpp" namespace gui { diff --git a/src/gui/widget/timeline/timeline-clip.hpp b/src/gui/widget/timeline/timeline-clip.hpp index 4a03a8c77..a62639f12 100644 --- a/src/gui/widget/timeline/timeline-clip.hpp +++ b/src/gui/widget/timeline/timeline-clip.hpp @@ -22,6 +22,7 @@ /** @file timeline-clip.hpp ** Representation of a clip on the timeline + ** @warning as of 2016 the entire timeline display is planned to be reworked */ #ifndef GUI_WIDGET_TIMELINE_CLIP_H diff --git a/src/gui/widget/timeline/timeline-entity.cpp b/src/gui/widget/timeline/timeline-entity.cpp index 672f3e9c1..da3d4086f 100644 --- a/src/gui/widget/timeline/timeline-entity.cpp +++ b/src/gui/widget/timeline/timeline-entity.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-entity.cpp + ** Implementation of a generic element to be placed onto the timeline + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/widget/timeline/timeline-entity.hpp" #include "gui/widget/timeline/draw-strategy.hpp" diff --git a/src/gui/widget/timeline/timeline-entity.hpp b/src/gui/widget/timeline/timeline-entity.hpp index 4abcea59e..381962f37 100644 --- a/src/gui/widget/timeline/timeline-entity.hpp +++ b/src/gui/widget/timeline/timeline-entity.hpp @@ -22,7 +22,8 @@ /** @file timeline-entity.hpp - ** any UI element that can be placed on the timeline. + ** Any UI element that can be placed on the timeline. + ** @warning as of 2016 the entire timeline display is planned to be reworked */ #ifndef GUI_WIDGET_TIMELINE_ENTITY_H diff --git a/src/gui/widget/timeline/timeline-group-track.cpp b/src/gui/widget/timeline/timeline-group-track.cpp index 13ec31340..f8b3c4c42 100644 --- a/src/gui/widget/timeline/timeline-group-track.cpp +++ b/src/gui/widget/timeline/timeline-group-track.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-group-track.cpp + ** @deprecated to be replaced by a different implementation approach + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-group-track.hpp" #include "gui/widget/timeline-widget.hpp" diff --git a/src/gui/widget/timeline/timeline-group-track.hpp b/src/gui/widget/timeline/timeline-group-track.hpp index aa65f9848..6120116f6 100644 --- a/src/gui/widget/timeline/timeline-group-track.hpp +++ b/src/gui/widget/timeline/timeline-group-track.hpp @@ -21,6 +21,13 @@ */ +/** @file timeline-group-track.hpp + ** Preliminary implementation of a group track within the timeline display + ** @deprecated to be replaced by a different implementation approach + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_GROUP_TRACK_H #define GUI_WIDGET_TIMELINE_GROUP_TRACK_H diff --git a/src/gui/widget/timeline/timeline-header-container.cpp b/src/gui/widget/timeline/timeline-header-container.cpp index d7616812d..7a98c5353 100644 --- a/src/gui/widget/timeline/timeline-header-container.cpp +++ b/src/gui/widget/timeline/timeline-header-container.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-header-container.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-header-container.hpp" #include "gui/widget/timeline/timeline-track.hpp" #include "gui/widget/timeline-widget.hpp" diff --git a/src/gui/widget/timeline/timeline-header-container.hpp b/src/gui/widget/timeline/timeline-header-container.hpp index 87a94ca2f..84ee305f6 100644 --- a/src/gui/widget/timeline/timeline-header-container.hpp +++ b/src/gui/widget/timeline/timeline-header-container.hpp @@ -21,6 +21,14 @@ */ +/** @file timeline-header-container.hpp + ** A container to hold the header area of the timeline display. + ** Most notably this was used to create a first version of the patchbay + ** and control areas for the tracks. Very likely to be completely rewritten. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_HEADER_CONTAINER_H #define GUI_WIDGET_TIMELINE_HEADER_CONTAINER_H diff --git a/src/gui/widget/timeline/timeline-header-widget.cpp b/src/gui/widget/timeline/timeline-header-widget.cpp index 454e3c8f1..fab001e9d 100644 --- a/src/gui/widget/timeline/timeline-header-widget.cpp +++ b/src/gui/widget/timeline/timeline-header-widget.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-header-widget.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline-widget.hpp" #include "gui/util/rectangle.hpp" diff --git a/src/gui/widget/timeline/timeline-header-widget.hpp b/src/gui/widget/timeline/timeline-header-widget.hpp index c2151a662..ed4bbecda 100644 --- a/src/gui/widget/timeline/timeline-header-widget.hpp +++ b/src/gui/widget/timeline/timeline-header-widget.hpp @@ -21,6 +21,12 @@ */ +/** @file timeline-header-widget.hpp + ** Widget to generate the timeline header + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_HEADER_WIDGET_H #define GUI_WIDGET_HEADER_WIDGET_H diff --git a/src/gui/widget/timeline/timeline-ibeam-tool.cpp b/src/gui/widget/timeline/timeline-ibeam-tool.cpp index b16cd4ed9..b0f6f937b 100644 --- a/src/gui/widget/timeline/timeline-ibeam-tool.cpp +++ b/src/gui/widget/timeline/timeline-ibeam-tool.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file timeline-ibeam-tool.cpp + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-ibeam-tool.hpp" #include "gui/widget/timeline-widget.hpp" #include "lib/time/mutation.hpp" diff --git a/src/gui/widget/timeline/timeline-ibeam-tool.hpp b/src/gui/widget/timeline/timeline-ibeam-tool.hpp index 95fec042b..f35778cd4 100644 --- a/src/gui/widget/timeline/timeline-ibeam-tool.hpp +++ b/src/gui/widget/timeline/timeline-ibeam-tool.hpp @@ -23,6 +23,7 @@ /** @file timeline-ibeam-tool.hpp ** A tool to select ranges in the timeline + ** @warning as of 2016 the entire timeline display is planned to be reworked */ #ifndef GUI_WIDGET_TIMELINE_IBEAM_TOOL_H diff --git a/src/gui/widget/timeline/timeline-layout-helper.cpp b/src/gui/widget/timeline/timeline-layout-helper.cpp index af7997532..139542036 100644 --- a/src/gui/widget/timeline/timeline-layout-helper.cpp +++ b/src/gui/widget/timeline/timeline-layout-helper.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-layout-helper.cpp + ** Preliminary implementation of Timeline presentation, layout helper. + ** @deprecated as of 2016 this class will become obsolete and replaced by a different implementation approach + */ + + #include "gui/widget/timeline/timeline-layout-helper.hpp" #include "gui/widget/timeline-widget.hpp" #include "gui/model/sequence.hpp" diff --git a/src/gui/widget/timeline/timeline-layout-helper.hpp b/src/gui/widget/timeline/timeline-layout-helper.hpp index a7fcce429..1516f1f9e 100644 --- a/src/gui/widget/timeline/timeline-layout-helper.hpp +++ b/src/gui/widget/timeline/timeline-layout-helper.hpp @@ -20,8 +20,9 @@ */ /** @file timeline-layout-helper.cpp - ** This file contains the definition of the layout helper class + ** Preliminary implementation of Timeline presentation, layout helper. ** @todo this class should be thoroughly reworked; it seems to be kind of a "god class" ////////TODO 5/2015 + ** @deprecated as of 2016 this class will become obsolete and replaced by a different implementation approach */ diff --git a/src/gui/widget/timeline/timeline-ruler.cpp b/src/gui/widget/timeline/timeline-ruler.cpp index ffe79d833..5324add22 100644 --- a/src/gui/widget/timeline/timeline-ruler.cpp +++ b/src/gui/widget/timeline/timeline-ruler.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-ruler.cpp + ** The ruler at the top of the timeline display to represent the time axis. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-ruler.hpp" #include "gui/widget/timeline-widget.hpp" #include "gui/workspace/style-manager.hpp" diff --git a/src/gui/widget/timeline/timeline-ruler.hpp b/src/gui/widget/timeline/timeline-ruler.hpp index 88201aebf..a90ad087b 100644 --- a/src/gui/widget/timeline/timeline-ruler.hpp +++ b/src/gui/widget/timeline/timeline-ruler.hpp @@ -21,6 +21,12 @@ */ +/** @file timeline-ruler.hpp + ** The ruler at the top of the timeline display to represent the time axis. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_RULER_H #define GUI_WIDGET_TIMELINE_RULER_H diff --git a/src/gui/widget/timeline/timeline-state.cpp b/src/gui/widget/timeline/timeline-state.cpp index 5c41c2db8..5f886d1d6 100644 --- a/src/gui/widget/timeline/timeline-state.cpp +++ b/src/gui/widget/timeline/timeline-state.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-state.cpp + ** Implementation of presentation state for the first draft of the timeline display. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-state.hpp" #include "lib/time/timevalue.hpp" #include "lib/time/mutation.hpp" diff --git a/src/gui/widget/timeline/timeline-state.hpp b/src/gui/widget/timeline/timeline-state.hpp index 59be1c784..e4a124eec 100644 --- a/src/gui/widget/timeline/timeline-state.hpp +++ b/src/gui/widget/timeline/timeline-state.hpp @@ -21,6 +21,13 @@ */ +/** @file timeline-state.hpp + ** Presentation state for the first draft of the timeline display. Very likely + ** to be replaced by a complete rewrite. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_STATE_H #define GUI_WIDGET_TIMELINE_STATE_H diff --git a/src/gui/widget/timeline/timeline-tool.cpp b/src/gui/widget/timeline/timeline-tool.cpp index cb7c20ce5..68b7625b0 100644 --- a/src/gui/widget/timeline/timeline-tool.cpp +++ b/src/gui/widget/timeline/timeline-tool.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-tool.cpp + ** Tools and working modes for selections in the timeline. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-tool.hpp" #include "gui/widget/timeline-widget.hpp" diff --git a/src/gui/widget/timeline/timeline-tool.hpp b/src/gui/widget/timeline/timeline-tool.hpp index ec04955d4..988edc0ba 100644 --- a/src/gui/widget/timeline/timeline-tool.hpp +++ b/src/gui/widget/timeline/timeline-tool.hpp @@ -21,6 +21,13 @@ */ +/** @file timeline-tool.hpp + ** Tools and working modes for selections in the timeline. Most notably + ** the Arrow tool for object selection and the I-Beam tool for range selection. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_TOOL_H #define GUI_WIDGET_TIMELINE_TOOL_H diff --git a/src/gui/widget/timeline/timeline-track.cpp b/src/gui/widget/timeline/timeline-track.cpp index 7f55189a2..65ce84fad 100644 --- a/src/gui/widget/timeline/timeline-track.cpp +++ b/src/gui/widget/timeline/timeline-track.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file timeline-track.cpp + ** A group track in the first draft version of the timeline display. + ** @todo as of 2016 this is about to be replaced by a new implementation approach + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-track.hpp" #include "gui/widget/timeline-widget.hpp" #include "gui/workspace/style-manager.hpp" diff --git a/src/gui/widget/timeline/timeline-track.hpp b/src/gui/widget/timeline/timeline-track.hpp index e82e73ac2..4edefa174 100644 --- a/src/gui/widget/timeline/timeline-track.hpp +++ b/src/gui/widget/timeline/timeline-track.hpp @@ -21,6 +21,13 @@ */ +/** @file timeline-track.hpp + ** A group track in the first draft version of the timeline display. + ** @todo as of 2016 this is about to be replaced by a new implementation approach + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_TRACK_H #define GUI_WIDGET_TIMELINE_TRACK_H diff --git a/src/gui/widget/timeline/timeline-view-window.cpp b/src/gui/widget/timeline/timeline-view-window.cpp index 30452296e..65b68c040 100644 --- a/src/gui/widget/timeline/timeline-view-window.cpp +++ b/src/gui/widget/timeline/timeline-view-window.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-view-window.cpp + ** Implementation of the timeline window, which holds the main timeline display. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline/timeline-view-window.hpp" #include "gui/widget/timeline-widget.hpp" diff --git a/src/gui/widget/timeline/timeline-view-window.hpp b/src/gui/widget/timeline/timeline-view-window.hpp index fc5b255ff..19405279c 100644 --- a/src/gui/widget/timeline/timeline-view-window.hpp +++ b/src/gui/widget/timeline/timeline-view-window.hpp @@ -21,6 +21,12 @@ */ +/** @file timeline-view-window.hpp + ** Helper to manage the timeline window, which holds the main timeline display. + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_VIEW_WINDOW_H #define GUI_WIDGET_TIMELINE_VIEW_WINDOW_H diff --git a/src/gui/widget/timeline/timeline-zoom-scale.cpp b/src/gui/widget/timeline/timeline-zoom-scale.cpp index ca891401d..694b6c428 100644 --- a/src/gui/widget/timeline/timeline-zoom-scale.cpp +++ b/src/gui/widget/timeline/timeline-zoom-scale.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file timeline-zoom-scale.cpp + ** Widget to control timeline zoom scale + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #include "gui/widget/timeline-widget.hpp" #include "gui/widget/timeline/timeline-zoom-scale.hpp" diff --git a/src/gui/widget/timeline/timeline-zoom-scale.hpp b/src/gui/widget/timeline/timeline-zoom-scale.hpp index e95150ab2..f9d6f41e2 100644 --- a/src/gui/widget/timeline/timeline-zoom-scale.hpp +++ b/src/gui/widget/timeline/timeline-zoom-scale.hpp @@ -21,6 +21,12 @@ */ +/** @file timeline-zoom-scale.hpp + ** Widget to control timeline zoom scale + ** @warning as of 2016 the entire timeline display is planned to be reworked + */ + + #ifndef GUI_WIDGET_TIMELINE_ZOOM_SCALE_H #define GUI_WIDGET_TIMELINE_ZOOM_SCALE_H diff --git a/src/gui/widget/video-display-widget.cpp b/src/gui/widget/video-display-widget.cpp index fb976021f..482ca54a9 100644 --- a/src/gui/widget/video-display-widget.cpp +++ b/src/gui/widget/video-display-widget.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file video-display-widget.cpp + ** Implementation of video display, embedded into the UI. + */ + + #include "gui/gtk-lumiera.hpp" #include "gui/output/xvdisplayer.hpp" #include "gui/output/gdkdisplayer.hpp" diff --git a/src/gui/widget/video-display-widget.hpp b/src/gui/widget/video-display-widget.hpp index 0586c4ee0..451bc4074 100644 --- a/src/gui/widget/video-display-widget.hpp +++ b/src/gui/widget/video-display-widget.hpp @@ -21,6 +21,11 @@ */ +/** @file video-display-widget.hpp + ** Widget to create a video display embedded into the UI + */ + + #ifndef GUI_WIDGET_VIDEO_DISPLAY_WIDGET_H diff --git a/src/gui/workspace/panel-manager.cpp b/src/gui/workspace/panel-manager.cpp index aaf2f3c55..9a027b323 100644 --- a/src/gui/workspace/panel-manager.cpp +++ b/src/gui/workspace/panel-manager.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file panel-manager.cpp + ** Implementation of dockable UI panels, implemented with the + ** help of lib GDL (»Gnome Docking Libraray«, formerly aka »Gnome Design Library«) + */ + + #include "gui/workspace/panel-manager.hpp" #include "gui/panel/assets-panel.hpp" diff --git a/src/gui/workspace/workspace-window.cpp b/src/gui/workspace/workspace-window.cpp index 54cf4c1d2..fa6905c09 100644 --- a/src/gui/workspace/workspace-window.cpp +++ b/src/gui/workspace/workspace-window.cpp @@ -20,6 +20,11 @@ * *****************************************************/ + +/** @file workspace-window.cpp + ** Implementation of base functionality for workspace windows. + */ + #include "gui/gtk-lumiera.hpp" #include "gui/config-keys.hpp" #include "gui/workspace/workspace-window.hpp" 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 diff --git a/src/include/dummy-player-facade.h b/src/include/dummy-player-facade.h index ed59818c4..6a11672d4 100644 --- a/src/include/dummy-player-facade.h +++ b/src/include/dummy-player-facade.h @@ -21,6 +21,10 @@ */ +/** @file dummy-player-facade.h + */ + + #ifndef PROC_INTERFACE_DUMMYPLAYER_H #define PROC_INTERFACE_DUMMYPLAYER_H diff --git a/src/include/interfaceproxy.hpp b/src/include/interfaceproxy.hpp index 05c6ead6c..78ef4b9ee 100644 --- a/src/include/interfaceproxy.hpp +++ b/src/include/interfaceproxy.hpp @@ -22,7 +22,7 @@ /** @file interfaceproxy.hpp ** Facade Interfaces Lifecycle. Communication between the Layers within Lumiera - ** usually is routed through Layer Separation Interfaces. These are comprised + ** usually is routed through *Layer Separation Interfaces*. These are comprised ** of a Facade interface and a equivalent rendering as C Language interface defined ** with the help of the Interface/Plugin system. But in order to be able to actually ** access a service via this Facade, you need an instance of the interface. @@ -33,12 +33,12 @@ ** Typically there is another subclass of the Facade interfaces sitting "on the other side" ** of the interface barrier and actually implementing the functionality. The template ** facade::Accessor can be thought of as a factory creating such a proxy instance of the - ** facade interface for the client code to use. Typically, an instance of the \em factory + ** facade interface for the client code to use. Typically, an instance of the _factory_ ** is embedded (as a static functor member object) right within the otherwise abstract - ** facade interface, this way allowing the client code to write e.g. \c XYZInterface::facade() - ** to yield a reference to a proxy object implementing \c XYZInterface. + ** facade interface, this way allowing the client code to write e.g. `XYZInterface::facade()` + ** to yield a reference to a proxy object implementing `XYZInterface`. ** - ** Interface Lifecycle + ** # Interface Lifecycle ** ** Instances of an Interface are either directly provided by some facility within the core, ** or they are loaded from a shared module (plugin). In either case this means the interface @@ -63,8 +63,8 @@ ** While client code just includes the interface header (including interfaceproxy.hpp ** in turn), there needs to be an actual implementation of each proxy object located in ** some translation unit. The usual place is interfaceproxy.cpp, which gets linked into - ** \c liblumieracommon.so and contains actual specialisations and literal forwarding - ** code for each individual facade. + ** `liblumieracommon.so` and contains actual specialisations and literal forwarding + ** code _for each individual facade._ ** ** @see interface.h ** @see plugin.h diff --git a/src/include/play-facade.h b/src/include/play-facade.h index fced03316..ecfc536a7 100644 --- a/src/include/play-facade.h +++ b/src/include/play-facade.h @@ -21,6 +21,11 @@ */ +/** @file play-facade.h + ** Public access point to the _playback service_ provided by the »play-out subsystem« + */ + + #ifndef PROC_INTERFACE_PLAY_H #define PROC_INTERFACE_PLAY_H diff --git a/src/lib/allocation-cluster.cpp b/src/lib/allocation-cluster.cpp index 5baeded2b..2ca5d89f8 100644 --- a/src/lib/allocation-cluster.cpp +++ b/src/lib/allocation-cluster.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file allocation-cluster.cpp + ** Implementation of [memory management helper functions](\ref allocation-cluster.hpp) + ** for the render engine model. Here, in the actual translation unit, the generic part + ** of these functions is emitted, while the corresponding header provides a strictly + ** typed front-end, based on templates, which forward to the implementation eventually. + */ + + #include "lib/allocation-cluster.hpp" #include "lib/error.hpp" #include "lib/util.hpp" diff --git a/src/lib/bool-checkable.hpp b/src/lib/bool-checkable.hpp index b9c3d81f7..529ee521b 100644 --- a/src/lib/bool-checkable.hpp +++ b/src/lib/bool-checkable.hpp @@ -21,6 +21,24 @@ */ +/** @file bool-checkable.hpp + ** Mix-in for implicit conversion to bool. + ** When inheriting from BoolCheckable, a class becomes convertible + ** to `bool` -- which is implemented by invoking an operation `isValid()` + ** on this class. + ** + ** @deprecated 2016 it is not clear if we'll retain that feature on the long run. + ** Essentially this was needed to work around the dangers of implicit `bool` + ** conversion in C++98, which is largely obsolete since C++11, because the + ** rectified semantics of implicit conversion now prevent most unexpected + ** usages of this conversion function, like e.g. in comparison operators + ** on a derived class. Moreover, fun fact is, the implementation in this + ** header is not even correct, see Ticket #477 + ** On the other hand, the basic idea of exposing a `isValid()` function + ** does not sound too bad... + */ + + #ifndef LIB_BOOL_CHECKABLE_H #define LIB_BOOL_CHECKABLE_H diff --git a/src/lib/cmdline.cpp b/src/lib/cmdline.cpp index 174039840..1d3015fc7 100644 --- a/src/lib/cmdline.cpp +++ b/src/lib/cmdline.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file cmdline.cpp + ** Implementation of a wrapper / marker to handle "commandline arguments". + */ + + #include "lib/util.hpp" #include "include/logging.h" diff --git a/src/lib/cmdline.hpp b/src/lib/cmdline.hpp index 2dba98262..ec67eef25 100644 --- a/src/lib/cmdline.hpp +++ b/src/lib/cmdline.hpp @@ -21,6 +21,15 @@ */ +/** @file cmdline.hpp + ** Class to encapsulate the typical C-style commandline definition. + ** A Cmdline object takes the typical `int argc, int** argv` and _copies_ + ** the referred data into a vector of strings. Thus `Cmdline` is a way to + ** express explicitly on APIs that we are consuming commandline contents, + ** and, moreover, it offers a way more sane interface to deal with those. + */ + + #ifndef LIB_CMDLINE_H #define LIB_CMDLINE_H @@ -39,7 +48,7 @@ namespace lib { /** - * Abstraction of the usual "int argc, int** argv"-Commandline, + * Abstraction of the usual `int argc, int** argv`-Commandline, * to be able to treat it as a vector of strings. Inherits from * vector, but provides convenient conversions to * string (joining delimited by space)... diff --git a/src/lib/depend.hpp b/src/lib/depend.hpp index 5110789fd..68f05cad3 100644 --- a/src/lib/depend.hpp +++ b/src/lib/depend.hpp @@ -42,7 +42,7 @@ This code is heavily inspired by ** functions allows for subclass creation and various other kinds of service management. ** ** - ** \par Why Singletons? Inversion-of-Control and Dependency Injection + ** # Why Singletons? Inversion-of-Control and Dependency Injection ** ** Singletons are frequently over-used, and often they serve as disguised ** global variables to support a procedural programming style. As a remedy, typically @@ -53,19 +53,19 @@ This code is heavily inspired by ** Thus, for Lumiera, the choice to use Singletons was deliberate: we understand the ** Inversion-of-Control principle, yet we want to stay just below the level of building ** a central application manager core. At the usage site, we access a factory for some - ** service by name, where the »name« is actually the type name of an interface - ** or facade. Singleton is used as an implementation of this factory, when the service + ** service *by name*, where the »name« is actually the type name of an interface or + ** facade. Singleton is used as an _implementation_ of this factory, when the service ** is self-contained and can be brought up lazily. ** - ** \par Conventions, Lifecycle and Unit Testing + ** ## Conventions, Lifecycle and Unit Testing ** ** Usually we place an instance of the singleton factory (or some other kind of factory) ** as a static variable within the interface class describing the service or facade. ** As a rule, everything accessible as Singleton is sufficiently self-contained to come - ** up any time -- even prior to \c main(). But at shutdown, any deregistration must be - ** done explicitly using a lifecycle hook. Destructors aren't allowed to do any significant - ** work besides releasing references, and we acknowledge that singletons can be released - ** in \em arbitrary order. + ** up any time -- even prior to `main()`. But at shutdown, any deregistration must be done + ** explicitly using a lifecycle hook. Destructors aren't allowed to do _any significant work_ + ** beyond releasing references, and we acknowledge that singletons can be released + ** in _arbitrary order_. ** ** @see lib::Depend ** @see lib::DependencyFactory @@ -89,6 +89,7 @@ namespace lib { * Access point to singletons and other kinds of dependencies. * Actually this is a Factory object, which is typically placed into a * static field of the Singleton (target) class or some otherwise suitable interface. + * @param SI the class of the Singleton instance * @note uses static fields internally, so all factory configuration is shared per type * @remark there is an ongoing discussion regarding the viability of the * Double Checked Locking pattern, which requires either the context of a clearly defined @@ -98,6 +99,12 @@ namespace lib { * the singleton ctor to be flushed and visible to other threads when releasing the lock? * To my understanding, the answer is yes. See * [POSIX](http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_10) + * @remark we could consider to rely on a _Meyers Singleton_, where the compiler automatically + * generates the necessary code and guard variable to ensure single-threaded initialisation + * of the instance variable. But the downside of this approach is that we'd loose access + * to the singleton instance variable, which then resides within the scope of a single + * access function. Such would counterfeit the ability to exchange the instance to + * inject a mock for unit testing. * @todo as of 2016, the design could still be improved //////////////////////////////////////////TICKET #1086 * @param SI the class of the Singleton instance */ diff --git a/src/lib/dependency-factory.hpp b/src/lib/dependency-factory.hpp index f09848ad8..36297a6f5 100644 --- a/src/lib/dependency-factory.hpp +++ b/src/lib/dependency-factory.hpp @@ -21,6 +21,13 @@ */ +/** @file dependency-factory.hpp + ** Implementation of a singleton factory used to bring up services as dependency. + ** @internal this implementation header belongs to our framework to deal with + ** [service dependencies](\ref depend.hpp) and should not be used directly. + */ + + #ifndef LIB_DEPENDENCY_FACTORY_H @@ -40,7 +47,7 @@ namespace lib { /** * @internal Factory to generate and manage service objects classified by type. * An instance of this factory is placed once for each type for use by - * the \c lib::Depend front-end for dependency management. While the latter + * the lib::Depend front-end for dependency management. While the latter * provides the singleton-style initialisation patter, the DependencyFacotry * maintains a customisable factory function for instance creation. Moreover, * the embedded helper template DependencyFactory::InstanceHolder actually diff --git a/src/lib/frameid.hpp b/src/lib/frameid.hpp index 48a5ffe6b..40adadfbc 100644 --- a/src/lib/frameid.hpp +++ b/src/lib/frameid.hpp @@ -21,6 +21,18 @@ */ +/** @file frameid.hpp + ** Marker tuple to identify a specific frame. + ** @todo 2016 the intention was to use this as cache key, and to include + ** some information regarding the processing chain which led up to + ** the calculation of this frame, to allow for intelligent caching + ** and to avoid throwing away most of the frames on each and every + ** tweak of the edit. This marker was added as a preview in 2010 + ** but we didn't get to the point of actually putting that idea + ** into practical use. Yet the basic idea remains desirable... + */ + + #ifndef LUMIERA_FRAMEID_H #define LUMIERA_FRAMEID_H diff --git a/src/lib/hash-fnv.c b/src/lib/hash-fnv.c index 8f932400a..aad48343b 100644 --- a/src/lib/hash-fnv.c +++ b/src/lib/hash-fnv.c @@ -22,6 +22,12 @@ * *****************************************************/ +/** @file hash-fnv.c + ** Implementation of FNV ("Fowler-Noll-Vo") hashing functions. + ** @remarks code for this implementation is public domain + */ + + #include "lib/hash-fnv.h" #include diff --git a/src/lib/hash-fnv.h b/src/lib/hash-fnv.h index d8dc5640c..9d1c7a9bb 100644 --- a/src/lib/hash-fnv.h +++ b/src/lib/hash-fnv.h @@ -22,10 +22,9 @@ */ -/** - * @file hash-fnv.h - * Fowler-Noll-Vo Hashes. - * is a non-cryptographic hash function created by Glenn Fowler, Landon Curt Noll, and Phong Vo. +/** @file hash-fnv.h + ** Fowler-Noll-Vo Hashes. + ** FNV is a non-cryptographic hash function created by Glenn Fowler, Landon Curt Noll, and Phong Vo. */ diff --git a/src/lib/idi/genfunc.cpp b/src/lib/idi/genfunc.cpp index a1b5d4be3..c06c1c2ff 100644 --- a/src/lib/idi/genfunc.cpp +++ b/src/lib/idi/genfunc.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file genfunc.cpp + ** Implementation of generic functions to build identification schemes. + */ + + #include "lib/idi/genfunc.hpp" #include "lib/format-string.hpp" #include "lib/format-obj.hpp" diff --git a/src/lib/idi/genfunc.hpp b/src/lib/idi/genfunc.hpp index d4678bb5d..97872eba2 100644 --- a/src/lib/idi/genfunc.hpp +++ b/src/lib/idi/genfunc.hpp @@ -22,7 +22,7 @@ /** @file genfunc.hpp - ** Generic function to build identification schemes. + ** Generic functions to build identification schemes. ** These template functions are meant as common extension point. ** The purpose is to streamline and disentangle the various identification schemes ** in use at various places within Lumiera. We strive to cover all the common basic diff --git a/src/lib/lifecycle.cpp b/src/lib/lifecycle.cpp index 24bbf04ae..6b0f003c4 100644 --- a/src/lib/lifecycle.cpp +++ b/src/lib/lifecycle.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file lifecycle.cpp + ** Implementation of installable callbacks for lifecycle events. + */ + + #include "lib/error.hpp" #include "include/lifecycle.h" #include "lib/lifecycleregistry.hpp" diff --git a/src/lib/lockerror.c b/src/lib/lockerror.c index 2bd73809f..c1824a502 100644 --- a/src/lib/lockerror.c +++ b/src/lib/lockerror.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file lockerror.c + ** implementation and definitions for error-handling on low-level locking + */ + + #include "lib/lockerror.h" #include diff --git a/src/lib/lockerror.h b/src/lib/lockerror.h index 3c5293272..ba88a3918 100644 --- a/src/lib/lockerror.h +++ b/src/lib/lockerror.h @@ -19,6 +19,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file lockerror.h + ** definitions and declarations for error-handling on low-level locking + */ + #ifndef LUMIERA_LOCKERRORS_H #define LUMIERA_LOCKERRORS_H diff --git a/src/lib/luid.c b/src/lib/luid.c index d907060cb..86b965dcf 100644 --- a/src/lib/luid.c +++ b/src/lib/luid.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file luid.c + ** Implementation functions for Lumiera's unique object identifier (LUID). + */ + + #include "lib/luid.h" #include diff --git a/src/lib/meta/maybe-compare.hpp b/src/lib/meta/maybe-compare.hpp index cfa89ff6c..3564495ba 100644 --- a/src/lib/meta/maybe-compare.hpp +++ b/src/lib/meta/maybe-compare.hpp @@ -21,6 +21,11 @@ */ +/** @file maybe-compare.hpp + ** helpers for fail-safe invocation of comparison operations from generic code. + */ + + #ifndef LIB_META_MAYBE_COMPARE_H #define LIB_META_MAYBE_COMPARE_H diff --git a/src/lib/meta/no-instance.hpp b/src/lib/meta/no-instance.hpp index 73f7b71b0..800bed568 100644 --- a/src/lib/meta/no-instance.hpp +++ b/src/lib/meta/no-instance.hpp @@ -21,6 +21,24 @@ */ +/** @file no-instance.hpp + ** Metaprogramming helper to prevent an entity to be ever instantiated at runtime. + ** For Template Metaprogramming, we often define classes for the sole purpose of + ** forming a distinct type. Such helper types are established during compilation + ** and typically trigger the instantiation of further types from templates, while + ** there is never the intention to emit any actual code from these entities. + ** As a safety measure, such _stricly metaprogramming related_ facilities may be + ** marked to provoke a compilation failure, when the compiler -- accidentally -- + ** attempts to generate code to incorporate such an entity into the runtime world. + ** + ** \par example + ** The classical example is a marker type used to select one of various implementation + ** flavours of a given facility. In fact this helper was created to mark variations + ** based on the time code format in use. + ** @see timecode.hpp + */ + + #ifndef LIB_META_NO_INSTANCE_H #define LIB_META_NO_INSTANCE_H @@ -32,7 +50,7 @@ namespace meta{ /** * An Entity never to be instantiated. - * Marker baseclass for elements used for metaprogramming only. + * Marker baseclass for elements used in metaprogramming only. * Every attempt to instantiate such an element will cause an * compilation failure */ diff --git a/src/lib/meta/size-trait.hpp b/src/lib/meta/size-trait.hpp index 5a0ff6907..6eb7aaced 100644 --- a/src/lib/meta/size-trait.hpp +++ b/src/lib/meta/size-trait.hpp @@ -21,6 +21,30 @@ */ +/** @file size-trait.hpp + ** Metaprogramming definitions to deal with dependency on implementation size and layout. + ** Sometimes we need to build our code based on very specific assumptions regarding the + ** implementation data layout of library classes we rely on. Typically such happens when + ** we're forced to work around limitations the library provider never intended to be relevant + ** for any client. Which places us into the very unfortunate situation either to abandon some + ** design concept we prefer to use for some other relevant reason, or to do something very + ** evil and nasty (namely to rely on magic numbers, which may break silently when the + ** library provider changes implementation). + ** + ** While this situation can not be solved in principle, at least we may concentrate all + ** these nasty dependencies in a single location. Moreover, we can deal with this situation + ** by constructing our _magic numbers_ at least in a systematic way, which allows us to + ** intersperse static assertions to trigger an alarm when adjustments need to be made. + ** + ** \par typical example + ** A prominent example is boost::format, which causes a lot of code size bloat when used + ** liberally. For that reason, we built a front-end to encapsulate the boost implementation, + ** so any typed flavour of any call needs to be instantiated only once per application. + ** This allows us to use type safe formatting in error messages, but unfortunately forces + ** us to rely on the precise size of the boost::format implementation. + */ + + #ifndef LIB_META_SIZE_TRAIT_H #define LIB_META_SIZE_TRAIT_H diff --git a/src/lib/meta/trait-special.hpp b/src/lib/meta/trait-special.hpp index 8a18b6d19..3dc1d66a5 100644 --- a/src/lib/meta/trait-special.hpp +++ b/src/lib/meta/trait-special.hpp @@ -21,6 +21,19 @@ */ +/** @file trait-special.hpp + ** Rarely used specialisations of otherwise heavily used generic code. + ** Over time, we've established a set of tiny (meta)programming helpers, used + ** pervasively all over the code base. Such widely used (header) includes incur + ** the danger to increase compilation time and code size, and thus we spent some + ** effort on optimising the dependencies of these headers. Typically, such + ** analyse reveals some obscure and rare extension, which, while used occasionally, + ** maybe even only once, would cause some increase in the "include size profile". + ** + ** The obvious remedy is to move those into a separate header. + */ + + #ifndef LIB_META_TRAIT_SPECIAL_H #define LIB_META_TRAIT_SPECIAL_H diff --git a/src/lib/mpool.c b/src/lib/mpool.c index 724521c6f..9aaa93a01 100644 --- a/src/lib/mpool.c +++ b/src/lib/mpool.c @@ -19,6 +19,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file mpool.c + ** Implementation of pooling memory allocation functions for constant sized objects. + */ + #include #include #include diff --git a/src/lib/mpool.h b/src/lib/mpool.h index b59ea2b58..f4ab30369 100644 --- a/src/lib/mpool.h +++ b/src/lib/mpool.h @@ -19,50 +19,40 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file mpool.h + ** Pooled memory allocator for constant sized objects + ** *Memory Pools* are implemented as clusters of fixed sized elements. New clusters + ** are allocated on demand or manually preallocated with a mpool_reserve() operation. + ** Some efforts are taken to ensure (cache) locality of the provided memory. + ** All functions are reentrant but not threadsafe, if this is desired it is advised to + ** care for proper locking elsewhere. + ** @warning as of 2016, this is a stalled development effort towards a pooling allocator. + ** An initial working draft was created in 2009, but never challenged by any + ** widespread use beyond some test code. We acknowledge that there _will be_ + ** some kind of optimised allocator -- yet for the time being we rely on + ** several preliminary front-ends, which _could be attached_ to such an + ** allocator eventually, but use plain flat heap allocations right now. + */ + #include #include #include "lib/llist.h" #include "include/logging.h" -/* -//mpool Memory Pools -//mpool ------------ -//mpool -//mpool This memory pools are implemented as clusters of fixed sized elements. New clusters -//mpool are allocated on demand or manually preallocated with a `reserve()` operation. -//mpool Some efforts are taken to ensure (cache) locality of the provided memory. -//mpool All functions are reentrant but not threadsafe, if this is desired it is advised to -//mpool care for proper locking elsewhere. -//mpool -*/ - - -/* -//index.mpool_destroy_fn xref:mpool_destroy_fn[mpool_destroy_fn]:: function prototype for destroying elements -//mpool [[mpool_destroy_fn]] -//mpool .mpool_destroy_fn -//mpool When a memory pool gets destroyed it can call a destructor for any element which is still in the pool. -//mpool This destructor is optional. -//mpool -//mpool typedef void (*mpool_destroy_fn)(void* self) -//mpool -//mpool `self`:: -//mpool element to be destroyed -//mpool -*/ +/** + * Function prototype for destroying elements. + * When a memory pool gets destroyed it can call a destructor for any element which is still in the pool. + * Use of such a destructor is optional. + * @param self element to be destroyed + */ typedef void (*mpool_destroy_fn)(void* self); -/* -//index.struct_mpool xref:struct_mpool[mpool (struct)]:: the memory pool management structure -//mpool [[struct_mpool]] -//mpool .mpool -//mpool typedef struct mpool_struct mpool -//mpool typedef mpool* MPool -//mpool typedef const mpool* const_MPool -//mpool -//mpool This structure should be considered opaque. -*/ +/** + * memory pool management structure. + * This structure should be considered opaque. + */ typedef struct mpool_struct mpool; typedef mpool* MPool; typedef const mpool* const_MPool; @@ -91,81 +81,46 @@ extern void (*mpool_init_hook) (MPool self); /** called before a mpool gets destroyed */ extern void (*mpool_destroy_hook) (MPool self); -/* -//index.mpool_init xref:mpool_init[mpool_init()]:: Initialise a new memory pool -//mpool [[mpool_init]] -//mpool .mpool_init -//mpool Initialise a memory pool, memory pools must be initialised before being used. One can supply -//mpool an optional destructor function for elements, this will be used to destroy elements which are still -//mpool in the pool when it gets destroyed itself. The destructor is _NOT_ called when elements are freed. -//mpool -//mpool MPool mpool_init (MPool self, size_t elem_size, unsigned elements_per_cluster, mpool_move_fn mv, mpool_destroy_fn dtor) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool structure to be initialised -//mpool `elem_size`:: -//mpool size for a single element -//mpool `elements_per_cluster`:: -//mpool how many elements to put into a cluster -//mpool `dtor`:: -//mpool pointer to an optional destructor function or NULL -//mpool return:: -//mpool self -//mpool -*/ +/** + * Initialise a new memory pool. + * Memory pools must be initialised before being used. One can supply + * an optional destructor function for elements, this will be used to destroy elements which are still + * in the pool when it gets destroyed itself. The destructor is _NOT_ called when elements are freed. + * @param self pointer to the memory pool structure to be initialised + * @param elem_size size for a single element + * @param elements_per_cluster how many elements to put into a cluster + * @param dtor pointer to an optional destructor function, may be `NULL` + * @return `self` pointer to the initialised object + */ MPool mpool_init (MPool self, size_t elem_size, unsigned elements_per_cluster, mpool_destroy_fn dtor); -/* -//index.mpool_destroy xref:mpool_destroy[mpool_destroy()]:: destroy a memory pool -//mpool [[mpool_destroy]] -//mpool .mpool_destroy -//mpool A memory pool is not used anymore it should be destroyed. This frees all memory allocated with it. -//mpool When a destructor was provided at construction time, then this destructor is used on all non free elements -//mpool before before the clusters are freed. If no destructor was given then the clusters are just freed. -//mpool The destroyed memory pool behaves as if it was freshly initialised and can be used again, this is some kindof -//mpool exceptional behaviour. -//mpool -//mpool MPool mpool_destroy (MPool self) -//mpool -//mpool `self`:: -//mpool pointer to an initialised memory pool to be destroyed. -//mpool return:: -//mpool self -//mpool -//mpool -*/ +/** + * destroy a memory pool. + * A memory pool not used anymore should be destroyed. This frees all memory allocated with it. + * When a destructor was provided at construction time, then this destructor is used on all non free elements + * before before the clusters are freed. If no destructor was given then the clusters are just freed. + * The destroyed memory pool behaves as if it was freshly initialised and can be used again, this is + * some kind of exceptional behaviour. + * @param self pointer to an initialised memory pool to be destroyed. + * @return `self` + */ MPool mpool_destroy (MPool self); -/* -//index.mpool_purge xref:mpool_purge[mpool_purge()]:: free unused clusters -//mpool [[mpool_purge]] -//mpool .mpool_purge -//mpool -//mpool TODO -//mpool -//mpool -*/ +/** + * free unused clusters. + */ MPool mpool_purge (MPool self); -/* -//index.mpool_available xref:mpool_available[mpool_available()]:: query number of free elements -//mpool [[mpool_available]] -//mpool .mpool_available -//mpool One can check how much elements are available without a new cluster allocation in a memory pool. -//mpool -//mpool unsigned mpool_available (MPool self) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool to be queried -//mpool return:: -//mpool number of available elements -//mpool -*/ +/** + * query number of free elements. + * @param self pointer to the memory pool to be queried + * @return number of elements available in the pool _without allocating a new cluster_ + */ static inline unsigned mpool_available (MPool self) { @@ -173,98 +128,55 @@ mpool_available (MPool self) } -/* -//index.mpool_reserve xref:mpool_reserve[mpool_reserve()]:: preallocate elements -//mpool [[mpool_reserve]] -//mpool .mpool_reserve -//mpool Resize the pool that at least nelements become available without cluster reallocations -//mpool -//mpool unsigned mpool_reserve (MPool self, unsigned nelements) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool `nelements`:: -//mpool minimum number of elements to preallocate -//mpool return:: -//mpool self on success or NULL on error -//mpool -*/ +/** + * preallocate elements. + * Resize the pool that at least the given number of elements are available without cluster reallocations. + * @param self pointer to the memory pool + * @param nelements minimum number of elements to preallocate + * @return self on success or `NULL` on error + */ MPool mpool_reserve (MPool self, unsigned nelements); -/* -//index.mpool_alloc xref:mpool_alloc[mpool_alloc()]:: allocate one element -//mpool [[mpool_alloc]] -//mpool .mpool_alloc -//mpool Allocates on element from a mpool. To improve cache locality allocations -//mpool are grouped close together to recent allocations. -//mpool -//mpool void* mpool_alloc (MPool self) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool return:: -//mpool pointer to the allocated memory on success or NULL on error -//mpool will never fail when enough space was preallocated -//mpool -*/ +/** + * allocate one element from a MPool. To improve cache locality allocations + * are grouped close together to recent allocations. + * @param self pointer to the memory pool + * @return pointer to the allocated memory on success or `NULL` on error + * @note will never fail when enough space was preallocated + */ void* mpool_alloc (MPool self); -/* -//index.mpool_alloc_near xref:mpool_alloc_near[mpool_alloc_near()]:: allocate one element, w/ locality -//mpool [[mpool_alloc_near]] -//mpool .mpool_alloc_near -//mpool Allocates on element from a mpool. To improve cache locality the allocation -//mpool tries to get an element close to another. -//mpool -//mpool void* mpool_alloc_near (MPool self, void* near) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool `near`:: -//mpool reference to another element which should be close to the returned element (hint only) -//mpool return:: -//mpool pointer to the allocated memory on success or NULL on error -//mpool will never fail when enough space was preallocated -//mpool -*/ +/** + * allocate one element close to the given reference element. + * To improve cache locality the allocation tries to get an element close by. + * @param self pointer to the memory pool + * @param near reference to another element which should be close to the returned element _(hint only)_ + * @return pointer to the allocated memory on success or `NULL` on error + * @note will never fail when enough space was preallocated + */ void* mpool_alloc_near (MPool self, void* near); -/* -//index.mpool_free xref:mpool_free[mpool_free()]:: free one element -//mpool [[mpool_free]] -//mpool .mpool_free -//mpool Frees the given element and puts it back into the pool for furhter allocations. -//mpool -//mpool void mpool_free (MPool self, void* element) -//mpool -//mpool `self`:: -//mpool pointer to the memory pool -//mpool `element`:: -//mpool element to be freed -//mpool -*/ +/** + * free one element. + * Frees the given element and puts it back into the pool for further allocations. + * @param self pointer to the memory pool + * @param element element to be freed + */ void mpool_free (MPool self, void* element); +/** diagnostic dump of MPool allocation */ void nobug_mpool_dump (const_MPool self, const int depth, const struct nobug_context dump_context, void* extra); - -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ diff --git a/src/lib/mrucache.c b/src/lib/mrucache.c index 272d66a3e..cfcc2d25e 100644 --- a/src/lib/mrucache.c +++ b/src/lib/mrucache.c @@ -19,6 +19,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file mrucache.c + ** Implementation of a caching by most recent use. + */ + #include "lib/safeclib.h" #include "lib/mrucache.h" diff --git a/src/lib/mrucache.h b/src/lib/mrucache.h index eeb871981..e2ae8c03d 100644 --- a/src/lib/mrucache.h +++ b/src/lib/mrucache.h @@ -19,20 +19,22 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef LUMIERA_CACHE_H -#define LUMIERA_CACHE_H + +/** @file mrucache.h + ** Most recent used cache. + ** Elements (addressed by a LList node) are either checked in the cache and thereby subject of aging + ** or checked out under control of the user. Most operations require that the cache is locked. + ** @warning not threadsafe. Locking must be done from usage site. + */ + + +#ifndef LIB_MRUCACHE_H +#define LIB_MRUCACHE_H #include "lib/llist.h" #include -/** - * @file - * Most recent used cache - * Elements (addressed by a LList node) are either checked in the cache and thereby subject of aging - * or checked out under control of the user. Most operations require that the cache is locked. This locking - * must be done from elsewhere. - */ /** * Callback function used to destroy/cleanup aged elements. @@ -176,4 +178,4 @@ int lumiera_mrucache_age (LumieraMruCache self, int nelem); -#endif +#endif /*LIB_MRUCACHE_H*/ diff --git a/src/lib/nobug-init.cpp b/src/lib/nobug-init.cpp index 9c2b3cb95..0c222275b 100644 --- a/src/lib/nobug-init.cpp +++ b/src/lib/nobug-init.cpp @@ -21,7 +21,13 @@ * *****************************************************/ -#include "lib/nobug-init.hpp" +/** @file nobug-init.cpp + ** Implementation function for automatic trigger of NoBug initialisation + ** @note `#include` nobug-init.hpp to use this initialisation automatically + */ + + +#include /// magic to generate NoBug logging definitions #define LUMIERA_NOBUG_INIT_CPP diff --git a/src/lib/nocopy.hpp b/src/lib/nocopy.hpp index 3f8fc8b36..e916306a3 100644 --- a/src/lib/nocopy.hpp +++ b/src/lib/nocopy.hpp @@ -21,6 +21,14 @@ */ +/** @file nocopy.hpp + ** Mix-Ins to allow or prohibit various degrees of copying and cloning. + ** @todo 2016 this could be organised way better. Also C++11 offers a way more + ** elegant way of expressing the intention. We could get rid of `boost::noncopyable` + ** The basic idea of using a marker mixin seems very reasonable though. ////////////////////////////TICKET #1084 + */ + + #ifndef LIB_NOCOPY_H #define LIB_NOCOPY_H diff --git a/src/lib/optional-ref.hpp b/src/lib/optional-ref.hpp index d9371fccd..ccdb72fe1 100644 --- a/src/lib/optional-ref.hpp +++ b/src/lib/optional-ref.hpp @@ -21,6 +21,13 @@ */ +/** @file optional-ref.hpp + ** a checked, switchable reference. + ** Offers semantics similar to a pointer, but throws (not segfaults) + ** on invalid dereferentiation + */ + + #ifndef LIB_OPTIONAL_REF_H #define LIB_OPTIONAL_REF_H diff --git a/src/lib/priqueue.c b/src/lib/priqueue.c index ab667047d..e32da1d84 100644 --- a/src/lib/priqueue.c +++ b/src/lib/priqueue.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file priqueue.c + ** a simple "text book" implementation of a priority queue, based on a binary heap + */ + + #include "lib/priqueue.h" #include "include/logging.h" diff --git a/src/lib/psplay.c b/src/lib/psplay.c index e28840476..478441f60 100644 --- a/src/lib/psplay.c +++ b/src/lib/psplay.c @@ -21,6 +21,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file psplay.c + ** Probabilistic splay tree implementation + */ + #include "include/logging.h" #include "lib/psplay.h" diff --git a/src/lib/psplay.h b/src/lib/psplay.h index f88ac8cb5..5bad01128 100644 --- a/src/lib/psplay.h +++ b/src/lib/psplay.h @@ -21,23 +21,25 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ -#ifndef PSPLAY_H -#define PSPLAY_H + +/** @file psplay.h + ** Probabilistic splay tree. + ** A splay trees is self-optimising (in contrast to self-balancing) datastructure. + ** We introduce here a probabilistic bottom up approach which reduces the splay costs. + ** Without affecting the performance. The randomisation gives also some insurance that + ** worst case situations are extremely unlikely. + ** + ** Tree nodes are very small (just 2 pointers) and are intrusively placed into the users + ** datastructure. + */ + + +#ifndef LIB_PSPLAY_H +#define LIB_PSPLAY_H #include #include -/** - * @file - * Probabilistic splay trees - * A splay trees is self-optimizing (in contrast to self-balancing) datastructure. - * We introduce here a probabilistic bottom up approach which reduces the splay costs. - * Without affecting the performance. The randomization gives also some insurance that - * worst case situations are extremely unlikely. - * Tree nodes are very small (just 2 pointers) and are intrusively placed into the users - * datastructure. - */ - /** * Type and handle for a psplay tree node @@ -283,11 +285,4 @@ psplay_walk (PSplay self, PSplaynode node, psplay_action_fn action, int level, v void psplay_dump (PSplay self, FILE* dest); -#endif -/* -// Local Variables: -// mode: C -// c-file-style: "gnu" -// indent-tabs-mode: nil -// End: -*/ +#endif /*LIB_PSPLAY_H*/ diff --git a/src/lib/query-diagnostics.hpp b/src/lib/query-diagnostics.hpp index 812d5bc03..f7283fe37 100644 --- a/src/lib/query-diagnostics.hpp +++ b/src/lib/query-diagnostics.hpp @@ -21,6 +21,11 @@ */ +/** @file query-diagnostics.hpp + ** diagnostic helpers to support test related to predicate queries + */ + + #ifndef LIB_QUERY_DIAGNOSTICS_H #define LIB_QUERY_DIAGNOSTICS_H diff --git a/src/lib/query-text.cpp b/src/lib/query-text.cpp index 41705cfce..6a3f152db 100644 --- a/src/lib/query-text.cpp +++ b/src/lib/query-text.cpp @@ -21,28 +21,21 @@ * *****************************************************/ -//#include "lib/util.hpp" -//#include "lib/symbol.hpp" -//#include "include/logging.h" +/** @file query-text.cpp + ** Implementation bits regarding a syntactical standard representation of predicate queries + */ + + #include "lib/query-text.hpp" -//#include #include #include -//#include -//using std::map; using std::string; -//using util::contains; -//using util::isnil; namespace lib { - namespace { // internal details - - } // internal details - /** Parse, verify and normalise the raw query definition * @warning right now (2012) we don't normalise at all diff --git a/src/lib/query-util.cpp b/src/lib/query-util.cpp index b6fdc6421..b370018d9 100644 --- a/src/lib/query-util.cpp +++ b/src/lib/query-util.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file query-util.cpp + ** Implementation of helpers for working with predicate queries. + */ + + #include "lib/error.hpp" #include "lib/query-util.hpp" #include "lib/util.hpp" diff --git a/src/lib/query-util.hpp b/src/lib/query-util.hpp index 092fe5dba..a76f4a6ca 100644 --- a/src/lib/query-util.hpp +++ b/src/lib/query-util.hpp @@ -21,6 +21,11 @@ */ +/** @file query-util.hpp + ** Utilities to support working with predicate queries + */ + + #ifndef LIB_QUERY_UTIL_H #define LIB_QUERY_UTIL_H diff --git a/src/lib/ref-array.hpp b/src/lib/ref-array.hpp index 341645678..32084f3a2 100644 --- a/src/lib/ref-array.hpp +++ b/src/lib/ref-array.hpp @@ -21,6 +21,13 @@ */ +/** @file ref-array.hpp + ** Abstraction interface: array-like access by subscript + ** @todo as of 2016, this concept seems very questionable: do we _really_ want + ** to abstract over random access, or do we _actually_ want for-iteration?? + */ + + #ifndef LIB_REF_ARRAY_H #define LIB_REF_ARRAY_H @@ -38,12 +45,14 @@ namespace lib { * @todo ouch -- a collection that isn't iterable... ///////////////////////TICKET #1040 */ template - struct RefArray : boost::noncopyable + class RefArray + : boost::noncopyable { + public: + virtual ~RefArray() {} ///< this is an interface + virtual T const& operator[] (size_t i) const =0; virtual size_t size() const =0; - - virtual ~RefArray() {} }; diff --git a/src/lib/safeclib.c b/src/lib/safeclib.c index 980353273..72fb9688a 100644 --- a/src/lib/safeclib.c +++ b/src/lib/safeclib.c @@ -17,7 +17,15 @@ 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 safeclib.c + ** Implementation of error-safe wrappers for some notorious C-Lib functions. + */ + + #include "lib/error.h" #include "lib/safeclib.h" diff --git a/src/lib/safeclib.h b/src/lib/safeclib.h index c1fe79554..2a6ab5fb0 100644 --- a/src/lib/safeclib.h +++ b/src/lib/safeclib.h @@ -1,5 +1,5 @@ /* - safe_clib.h - Portable and safe wrappers around some clib functions and some tools + SAFECLIB.h - Portable and safe wrappers around some clib functions and some tools Copyright (C) CinelerraCV 2008, Christian Thaeter @@ -19,14 +19,16 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file safeclib.h + ** Portable and safe wrappers around some C-Lib functions + */ + + #include "error.h" #include -/** - * @file - * Portable and safe wrappers around some clib functions and some tools - */ LUMIERA_ERROR_DECLARE(NO_MEMORY); /** diff --git a/src/lib/scoped-holder-transfer.hpp b/src/lib/scoped-holder-transfer.hpp index 5e1930e3a..2d19cc3cb 100644 --- a/src/lib/scoped-holder-transfer.hpp +++ b/src/lib/scoped-holder-transfer.hpp @@ -21,6 +21,13 @@ */ +/** @file scoped-holder-transfer.hpp + ** A mechanism to take ownership without allowing copy. + ** @deprecated obsolete concept, superseded by C++11 rvalue references + ** @todo expunge this! + */ + + #ifndef LIB_SCOPEDHOLDER_TRANSFER_H #define LIB_SCOPEDHOLDER_TRANSFER_H diff --git a/src/lib/searchpath.cpp b/src/lib/searchpath.cpp index f1bd470b2..5f20e7068 100644 --- a/src/lib/searchpath.cpp +++ b/src/lib/searchpath.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file searchpath.cpp + ** Implementation of helpers to handle directory search paths. + */ + + #include "lib/error.hpp" #include "lib/searchpath.hpp" #include "lib/symbol.hpp" diff --git a/src/lib/searchpath.hpp b/src/lib/searchpath.hpp index 35d787507..88a3f0c5b 100644 --- a/src/lib/searchpath.hpp +++ b/src/lib/searchpath.hpp @@ -21,6 +21,15 @@ */ +/** @file searchpath.hpp + ** Helpers to handle directory search paths. + ** The SerachPathSplitter allows to evaluate a "path" like specification + ** with colon separated components. It is complemented by some magic convenience + ** functions to self-discover the currently running executable and to resolve + ** the `$ORIGIN` pattern similar to what is known from linker `rpath` / `runpath` + */ + + #ifndef COMMON_SEARCHPATH_H #define COMMON_SEARCHPATH_H diff --git a/src/lib/sectionlock.h b/src/lib/sectionlock.h index 0eb6cd93b..1e2f3e056 100644 --- a/src/lib/sectionlock.h +++ b/src/lib/sectionlock.h @@ -19,6 +19,11 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ + +/** @file sectionlock.h + ** Mutex state handle for locked code sections + */ + #ifndef LUMIERA_SECTIONLOCK_H #define LUMIERA_SECTIONLOCK_H diff --git a/src/lib/test/depend-4test.hpp b/src/lib/test/depend-4test.hpp index b2abb385f..cdab44ff6 100644 --- a/src/lib/test/depend-4test.hpp +++ b/src/lib/test/depend-4test.hpp @@ -22,6 +22,11 @@ */ +/** @file depend-4test.hpp + ** test support code to inject mock variants of depencencies + */ + + #ifndef LIB_TEST_DEPEND_4TEST_H #define LIB_TEST_DEPEND_4TEST_H diff --git a/src/lib/test/event-log.cpp b/src/lib/test/event-log.cpp deleted file mode 100644 index 7f7ee60d9..000000000 --- a/src/lib/test/event-log.cpp +++ /dev/null @@ -1,44 +0,0 @@ -/* - EventLog - test facility to verify the occurrence of expected events - - Copyright (C) Lumiera.org - 2015, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "lib/test/event-log.hpp" -//#include "lib/format-string.hpp" - -//#include - -//using std::string; - -namespace lib { -namespace test{ - - namespace { // internal details - - } // internal details - - - -//Tangible::~Tangible() { } // Emit VTables here... - - - -}} // namespace lib::test diff --git a/src/lib/test/suite.cpp b/src/lib/test/suite.cpp index 44283aec3..3b3955e1d 100644 --- a/src/lib/test/suite.cpp +++ b/src/lib/test/suite.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file suite.cpp + ** Implementation of a simple test runner / test suite framework for unit testing. + */ + + #include "include/logging.h" #include "lib/hash-standard.hpp" diff --git a/src/lib/test/test-coll.hpp b/src/lib/test/test-coll.hpp index 01e24e9dc..28360c786 100644 --- a/src/lib/test/test-coll.hpp +++ b/src/lib/test/test-coll.hpp @@ -21,27 +21,24 @@ */ +/** @file test-coll.hpp + ** some bits of unit test helper code to fabricate collections with test data + */ + + #ifndef LIB_TEST_TEST_COLL_H #define LIB_TEST_TEST_COLL_H -//#include "lib/symbol.hpp" - -//#include -//#include #include #include #include #include -//#include namespace lib { namespace test{ -// using lib::Literal; -// using std::string; -// using std::rand; typedef std::vector VecI; @@ -100,14 +97,4 @@ namespace test{ }} // namespace lib::test - - - -/* === test helper macros === */ - -/** - * Macro to transmogrify... - */ -//#define MAGIC - -#endif +#endif /*LIB_TEST_TEST_COLL_H*/ diff --git a/src/lib/test/testdummy.hpp b/src/lib/test/testdummy.hpp index 27d4e79c7..5a6744c25 100644 --- a/src/lib/test/testdummy.hpp +++ b/src/lib/test/testdummy.hpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file testdummy.hpp + ** unittest helper code: test dummy object. + ** This dummy includes some distinct random identity marker + ** plus a checksum facility to verify instance management, i.e. + ** to verify each created instance was properly destroyed after use. + */ + + #include #include diff --git a/src/lib/test/testoption.cpp b/src/lib/test/testoption.cpp index 99ab9cb77..9f6f3718f 100644 --- a/src/lib/test/testoption.cpp +++ b/src/lib/test/testoption.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file testoption.cpp + ** Implementation of commandline parsing for the unittest test-suite. + */ + + #include "lib/error.hpp" #include "lib/test/testoption.hpp" #include "lib/test/suite.hpp" diff --git a/src/lib/test/testoption.hpp b/src/lib/test/testoption.hpp index 9691b7b82..0963ca6b7 100644 --- a/src/lib/test/testoption.hpp +++ b/src/lib/test/testoption.hpp @@ -21,6 +21,11 @@ */ +/** @file testoption.hpp + ** Commandline options for our unittest test-suite executable. + */ + + #ifndef TESTHELPER_TESTOPTION_H #define TESTHELPER_TESTOPTION_H diff --git a/src/lib/time/formats.hpp b/src/lib/time/formats.hpp index c463428c1..f1553af75 100644 --- a/src/lib/time/formats.hpp +++ b/src/lib/time/formats.hpp @@ -21,6 +21,16 @@ */ +/** @file formats.hpp + ** Definition of time code formats + ** This header is part of the Lumiera time and timecode handling library + ** and defines the interfaces and types to deal with the common set of + ** time code formats encountered in video editing. The generic handling + ** of _quantised time_ can be parametrised to support and comply to these + ** specific time code formats. + */ + + #ifndef LIB_TIME_FORMATS_H #define LIB_TIME_FORMATS_H diff --git a/src/lib/time/grid.hpp b/src/lib/time/grid.hpp index c02ae4a3d..50854ea30 100644 --- a/src/lib/time/grid.hpp +++ b/src/lib/time/grid.hpp @@ -21,6 +21,13 @@ */ +/** @file grid.hpp + ** definition of a time grid abstraction for time and timecode handling. + ** This interface is the foundation to deal with _quantised_ (grid aligned) + ** time values, as is essential for handling of timecode data. + */ + + #ifndef LIB_TIME_GRID_H #define LIB_TIME_GRID_H diff --git a/src/lib/time/quantiser.cpp b/src/lib/time/quantiser.cpp index f698e5b32..a2ed4372e 100644 --- a/src/lib/time/quantiser.cpp +++ b/src/lib/time/quantiser.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file quantiser.cpp + ** Implementation of support functions to create grid-aligned time and timecode values + */ + + #include "lib/time/quantiser.hpp" #include "lib/time/timevalue.hpp" #include "lib/time/timequant.hpp" diff --git a/src/lib/time/quantiser.hpp b/src/lib/time/quantiser.hpp index 989a2e875..4ed16703d 100644 --- a/src/lib/time/quantiser.hpp +++ b/src/lib/time/quantiser.hpp @@ -21,6 +21,21 @@ */ +/** @file quantiser.hpp + ** Library functions to support the formation of grid-aligned time values. + ** This is a crucial part of Lumiera's time and time handling framework; it + ** serves as link between the precise internal time representation and various + ** grid-aligned external standard time representations. The underlying theme is, + ** by forcing all conversions to go through this central set of library functions, + ** the notorious act of frame-aligning / grid-aligning time values, which can not + ** be avoided, will at least be performed in a reproducible and predictable way. + ** Moreover, the time handling library was built in a way such as to encourage + ** use of the internal, abstracted yet precise time entities, so that the + ** inevitable conversion to the imprecise but well-established external + ** entities (frame numbers, SMPTE, drop frame, HMS) happens as late as possible. + */ + + #ifndef LIB_TIME_QUANTISER_H #define LIB_TIME_QUANTISER_H @@ -30,7 +45,6 @@ #include "lib/time/timevalue.hpp" #include "lib/iter-adapter.hpp" -//#include #include #include #include diff --git a/src/lib/time/timecode.cpp b/src/lib/time/timecode.cpp index 27ffc0eae..8460516a5 100644 --- a/src/lib/time/timecode.cpp +++ b/src/lib/time/timecode.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file timecode.cpp + ** Implementation parts of the timecode handling library. + ** @todo a started implementation exists since 2010, + ** yet crucial parts still need to be filled in as of 2016 + */ + + #include "lib/time/timecode.hpp" #include "lib/time/timevalue.hpp" #include "lib/time/timequant.hpp" diff --git a/src/lib/time/timecode.hpp b/src/lib/time/timecode.hpp index 0493afdb7..bb3a8c5ea 100644 --- a/src/lib/time/timecode.hpp +++ b/src/lib/time/timecode.hpp @@ -21,6 +21,18 @@ */ +/** @file timecode.hpp + ** Timecode handling library + ** This header defines the foundation interface TCode to represent a grid aligned + ** time specification, given in some well-established time code format. It is complemented + ** by implementations of the most relevant practical time code formats + ** - frame numbers / frame counting + ** - SMPTE (hours, minutes, seconds and frames) -- including drop-frame + ** - HMS (hours, minutes, seconds and fractional seconds) + ** - fractional seconds as rational number + */ + + #ifndef LIB_TIME_TIMECODE_H #define LIB_TIME_TIMECODE_H @@ -45,7 +57,10 @@ namespace time { /** * Interface: fixed format timecode specification. * @see time::format - * @todo WIP-WIP-WIP + * @todo as of 2016 this is basically finished since years, + * but still not in any widespread practical use (not by bad intention, + * simply by lack of opportunities). So this core interface still needs + * some feedback from practice in order to be finalised. */ class TCode { diff --git a/src/lib/time/timequant.hpp b/src/lib/time/timequant.hpp index 98eb475e7..68ba6b614 100644 --- a/src/lib/time/timequant.hpp +++ b/src/lib/time/timequant.hpp @@ -21,6 +21,20 @@ */ +/** @file timequant.hpp + ** Support library to represent grid-aligned time specifications + ** This is part of Lumiera's time and time code handling framework. + ** The QuTime entity represents the link between the internal precise + ** time specifications and external representation formatted according + ** to some well established time code format: QuTime both holds a precise + ** internal time::TimeValue entry, plus a reference to the _time grid_ to + ** be used, when it comes to _quantising_ (grid-aligning) those values. + ** And it offers a dedicated API to "materialise" this (still complete and + ** precise) time value into an external representation. + ** + */ + + #ifndef LIB_TIME_TIMEQUANT_H #define LIB_TIME_TIMEQUANT_H diff --git a/src/lib/tmpbuf.c b/src/lib/tmpbuf.c index 46e42174a..f5993b959 100644 --- a/src/lib/tmpbuf.c +++ b/src/lib/tmpbuf.c @@ -1,5 +1,5 @@ /* - tmpbuf.c - Round Robin Temporary buffers + Tmpbuf - Round Robin Temporary buffers Copyright (C) Lumiera.org 2008, 2010 Christian Thaeter @@ -17,7 +17,18 @@ 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 tmpbuf.c + ** Implementation of temporary buffers with round-robin usage pattern. + ** + ** @warning this is the restored old version from bc989dab7a97fc69c (July 2010) + ** (the improved version is still buggy as of 5/2011) + */ + + #include "lib/safeclib.h" #include "lib/tmpbuf.h" @@ -29,11 +40,6 @@ #include -/*!! WARNING - *!! - *!! this is the restored old version from bc989dab7a97fc69c (July 2010) - *!! (the improved version is still buggy as of 5/2011) - */ struct lumiera_tmpbuf_struct { diff --git a/src/lib/tmpbuf.h b/src/lib/tmpbuf.h index 76b3ceaec..f67c7ef62 100644 --- a/src/lib/tmpbuf.h +++ b/src/lib/tmpbuf.h @@ -1,5 +1,5 @@ /* - tmpbuf.c - Round Robin Temporary buffers + TMPBUF.h - Round Robin Temporary buffers Copyright (C) Lumiera.org 2008, 2010 Christian Thaeter @@ -17,29 +17,37 @@ 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 tmpbuf.h + ** Round robin temporary buffers. + ** This helper provides some buffers per thread which are round-robin recycled with each use. + ** The idea is to have fast buffers for temporal data without need for explicit heap management. + ** There is a fixed number of buffers per thread, which will be re-used with a round-robin pattern, + ** without any safety checks. The caller just needs to ensure not to use too much of these buffers. + ** Typical usage is for "just printing a damn number", hand it over to a library, which will copy + ** the data anyway. + ** + ** @warning this is the restored old version from bc989dab7a97fc69c (July 2010) + ** (the improved version is still buggy as of 5/2011) + */ + + #ifndef LUMIERA_TMPBUF_H #define LUMIERA_TMPBUF_H #include -/** - * @file - * Round robin temporary buffers. - * This provides some buffers per thread which are round-robin recycled with each use. - * The idea is to have fast buffers for temporal data without need for explicit heap management. - * - * @warning this is the restored old version from bc989dab7a97fc69c (July 2010) - * (the improved version is still buggy as of 5/2011) - */ -/* following value must be exponent of 2 */ /** * Number of buffers in the ring * This also defines how many concurent buffers can be in use in one thread (including nested calls) * tmpbufs are only suitable for nested calls where one knows in advance how much tmpbufs might be used + * + * @warning the value defined here must be a power of 2 */ #define LUMIERA_TMPBUF_NUM 16 diff --git a/src/lib/util-quant.hpp b/src/lib/util-quant.hpp index 5648135b9..063ee430b 100644 --- a/src/lib/util-quant.hpp +++ b/src/lib/util-quant.hpp @@ -21,6 +21,11 @@ */ +/** @file util-quant.hpp + ** Utilities for quantisation (grid alignment) and comparisons. + */ + + #ifndef LIB_UTIL_QUANT_H #define LIB_UTIL_QUANT_H diff --git a/src/lib/util.cpp b/src/lib/util.cpp index 3b0660c2c..7ab8dfe67 100644 --- a/src/lib/util.cpp +++ b/src/lib/util.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file util.cpp + ** Implementation of widely used helper functions. + ** The helpers implemented here are typically accessed by including util.hpp, + ** so the reason of pushing down the implementation into a separate translation unit + ** (this one here) is to avoid more heavyweight includes (e.g. boost). + */ + + #include "lib/util.hpp" #include diff --git a/src/lib/util.hpp b/src/lib/util.hpp index c59675059..c3a3e6291 100644 --- a/src/lib/util.hpp +++ b/src/lib/util.hpp @@ -21,6 +21,19 @@ */ +/** @file 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. + ** There are several extensions and not-so-frequently used supplements packaged into + ** separate headers. + ** @warning be sure to understand the ramifications of including _anything_ here... + ** @see util-coll.hpp + ** @see uitl-foreach.hpp + ** @see util-quant.hpp + */ + + #ifndef LIB_UTIL_H #define LIB_UTIL_H diff --git a/src/lib/visitor-dispatcher.hpp b/src/lib/visitor-dispatcher.hpp index 3b264caed..0514cf0ef 100644 --- a/src/lib/visitor-dispatcher.hpp +++ b/src/lib/visitor-dispatcher.hpp @@ -21,6 +21,12 @@ */ +/** @file visitor-dispatcher.hpp + ** Helper for a trampoline table based implementation of the visitor pattern. + ** @internal implementation part, clients should include visitor.hpp + */ + + #ifndef LUMIERA_VISITOR_DISPATCHER_H #define LUMIERA_VISITOR_DISPATCHER_H diff --git a/src/lib/visitor.hpp b/src/lib/visitor.hpp index 08b3a8abc..f15eae4b0 100644 --- a/src/lib/visitor.hpp +++ b/src/lib/visitor.hpp @@ -36,8 +36,8 @@ Credits for many further implementation ideas go to /** @file visitor.hpp - ** A library implementation of the Visitor Pattern tailored specifically - ** to Lumiera's needs within the Proc Layer. Visitor enables double dispatch + ** A library implementation of the *Visitor Pattern* tailored specifically + ** to Lumiera's needs within the Proc Layer. Visitor enables *double dispatch* ** calls, based both on the concrete type of some target object and the concrete type of ** a tool object being applied to this target. The code carrying out this tool application ** (and thus triggering the double dispatch) need not know any of these concrete types and is @@ -47,22 +47,27 @@ Credits for many further implementation ideas go to ** concrete target visitable type. ** ** Implementation notes - **
  • driven by dispatch tables with trampoline functions.
    • - **
  • uses Typelists and Template metaprogramming to generate - ** Dispatcher tables for the concrete types.
    • - **
  • individual Visiting Tool implementation classes need to derive - ** from some Applicable > instantiation - ** and thus define which calls they get dispatched. This is \b crucial. - ** A concrete type not declared in this way will never be dispatched to this - ** concrete visiting tool implementation class. Of course, the latter is free - ** to implement corresponding "treat(ConcreteVisitable&) functions or fall back - ** on some treat(VisitableInterface&) function.
    • - **
  • any concrete Visitable subclass wanting to be treated by some concrete tool - ** needs to use the DECLARE_PROCESSABLE_BY(TOOLBASE) macro. By this, it gets an - ** virtual `apply(TOOLBASE&)` function. Otherwise, it will be treated by the - ** interface of the next base class using this macro.
    • - **
- ** For design questions and more detailed implementation notes, see the Proc Layer Tiddly Wiki. + ** - driven by dispatch tables with trampoline functions. + ** - uses Typelists and Template metaprogramming to generate + ** Dispatcher tables for the concrete types. + ** - individual Visiting Tool implementation classes need to derive + ** from some Applicable > instantiation + ** and thus define which calls they get dispatched. _This is crucial_. + ** A concrete type not declared in this way will never be dispatched to this + ** concrete visiting tool implementation class. Of course, the latter is free + ** to implement corresponding "treat(ConcreteVisitable&) functions or fall back + ** on some treat(VisitableInterface&) function. + ** - any concrete Visitable subclass wanting to be treated by some concrete tool + ** needs to use the `DECLARE_PROCESSABLE_BY(TOOLBASE)` macro. By this, it gets an + ** virtual `apply(TOOLBASE&)` function. Otherwise, it will be treated by the + ** interface of the next base class using this macro. + ** + ** @remarks as of 2016, it is not clear if we'll really use this facility; it was meant to play a + ** crucial role in the Builder (which is not implemented yet....). The fundamental idea of relying + ** on a visitor seems still adequate though. For design questions and more detailed implementation + ** notes, see the [TiddlyWiki]. + ** + ** [TiddlyWiki]: http://lumiera.org/wiki/renderengine.html#VisitorUse%20VisitingToolImpl%20BuilderStructures%20BuilderMechanics "Lumiera Tiddly Wiki" ** ** @see visitingtooltest.cpp test cases using our lib implementation ** @see BuilderTool one especially important instantiation diff --git a/src/lib/wrapperptr.hpp b/src/lib/wrapperptr.hpp index c2bd6a64c..6c3dfb224 100644 --- a/src/lib/wrapperptr.hpp +++ b/src/lib/wrapperptr.hpp @@ -21,6 +21,12 @@ */ +/** @file wrapperptr.hpp + ** Wrapper to treat several flavours of smart-pointers uniformly + ** @deprecated as of 2016 we should re-think how to organise visitor use in the Builder + */ + + #ifndef LUMIERA_WRAPPERPTR_H #define LUMIERA_WRAPPERPTR_H diff --git a/src/lumiera/main.cpp b/src/lumiera/main.cpp index 27bfa12a3..5dac8f32c 100644 --- a/src/lumiera/main.cpp +++ b/src/lumiera/main.cpp @@ -22,6 +22,11 @@ */ +/** @file main.cpp + ** Lumiera application main function + */ + + #include "include/logging.h" #include "lib/error.hpp" #include "common/appstate.hpp" diff --git a/src/proc/asset.cpp b/src/proc/asset.cpp index 09927cd91..e2c75276e 100644 --- a/src/proc/asset.cpp +++ b/src/proc/asset.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file asset.cpp + ** Default implementation of the [Asset abstraction](\ref asset.hpp) + */ + + #include "proc/asset.hpp" #include "proc/assetmanager.hpp" #include "lib/format-string.hpp" diff --git a/src/proc/asset/category.cpp b/src/proc/asset/category.cpp index 5016384d3..99c2e5d86 100644 --- a/src/proc/asset/category.cpp +++ b/src/proc/asset/category.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file category.cpp + ** Implementation parts regarding Asset categorisation + */ + + #include "proc/asset/category.hpp" #include "lib/util.hpp" #include "include/logging.h" diff --git a/src/proc/asset/category.hpp b/src/proc/asset/category.hpp index 1eddb6597..ce6028921 100644 --- a/src/proc/asset/category.hpp +++ b/src/proc/asset/category.hpp @@ -21,6 +21,11 @@ */ +/** @file category.hpp + ** Definition of Asset categorisation + */ + + #ifndef PROC_ASSET_CATEGORY_H #define PROC_ASSET_CATEGORY_H diff --git a/src/proc/asset/clip.cpp b/src/proc/asset/clip.cpp index 49483214e..405653185 100644 --- a/src/proc/asset/clip.cpp +++ b/src/proc/asset/clip.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file clip.cpp + ** Clip Asset implementation + */ + + #include "proc/asset/clip.hpp" #include "proc/mobject/session/mobjectfactory.hpp" ////TODO: avoidable? diff --git a/src/proc/asset/clip.hpp b/src/proc/asset/clip.hpp index 6117a58c4..6aed11ccc 100644 --- a/src/proc/asset/clip.hpp +++ b/src/proc/asset/clip.hpp @@ -21,6 +21,11 @@ */ +/** @file clip.hpp + ** Definition of Asset representation for a media clip + */ + + #ifndef ASSET_CLIP_H #define ASSET_CLIP_H diff --git a/src/proc/asset/codec.cpp b/src/proc/asset/codec.cpp deleted file mode 100644 index 08fd63713..000000000 --- a/src/proc/asset/codec.cpp +++ /dev/null @@ -1,31 +0,0 @@ -/* - Codec(Asset) - description of some media data decoder or encoder facility - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/asset/codec.hpp" - -namespace proc { -namespace asset { - - - -}} // namespace proc::asset diff --git a/src/proc/asset/codec.hpp b/src/proc/asset/codec.hpp index 093470859..eac62f1e4 100644 --- a/src/proc/asset/codec.hpp +++ b/src/proc/asset/codec.hpp @@ -21,6 +21,13 @@ */ +/** @file codec.hpp + ** Definition of a Codec Asset + ** @deprecated as of 2016 it seems questionable we'll have to deal with such assets, + ** since coding/decoding will always be delegated to widely available libraries. + */ + + #ifndef ASSET_CODEC_H #define ASSET_CODEC_H diff --git a/src/proc/asset/compoundmedia.cpp b/src/proc/asset/compoundmedia.cpp deleted file mode 100644 index 115ce7708..000000000 --- a/src/proc/asset/compoundmedia.cpp +++ /dev/null @@ -1,34 +0,0 @@ -/* - CompoundMedia - multichannel media - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/asset/compoundmedia.hpp" - -namespace proc { -namespace asset - { - - /** */ - - - - }} // namespace proc::asset diff --git a/src/proc/asset/compoundmedia.hpp b/src/proc/asset/compoundmedia.hpp index c73c2c7d9..2533bc5fa 100644 --- a/src/proc/asset/compoundmedia.hpp +++ b/src/proc/asset/compoundmedia.hpp @@ -21,6 +21,13 @@ */ +/** @file compoundmedia.hpp + ** Definition of an Asset to represent a clustering or compound of several media + ** @warning early draft, never put into use as of 2016 (but there wasn't a reason to + ** do so either, since we didn't get up to dealing with this topic) + */ + + #ifndef ASSET_COMPOUNDMEDIA_H #define ASSET_COMPOUNDMEDIA_H diff --git a/src/proc/asset/dataset.hpp b/src/proc/asset/dataset.hpp index 15d6f633c..0188ef778 100644 --- a/src/proc/asset/dataset.hpp +++ b/src/proc/asset/dataset.hpp @@ -21,6 +21,13 @@ */ +/** @file dataset.hpp + ** Definition of an Asset to represent a set of control data + ** An example would be captured animation data from some kind of external controller. + ** @warning as of 2016, this is a design placeholder. The concept seems reasonable though. + */ + + #ifndef ASSET_DATASET_H #define ASSET_DATASET_H diff --git a/src/proc/asset/db.hpp b/src/proc/asset/db.hpp index 3da42bfde..b0f097605 100644 --- a/src/proc/asset/db.hpp +++ b/src/proc/asset/db.hpp @@ -21,6 +21,13 @@ */ +/** @file db.hpp + ** Implementation of the _Asset database_. + ** Simplistic hash based lookup-table. + ** @internal implementation details of the AssetManager + */ + + #ifndef ASSET_DB_H #define ASSET_DB_H diff --git a/src/proc/asset/effect.cpp b/src/proc/asset/effect.cpp index 4230177c3..295837047 100644 --- a/src/proc/asset/effect.cpp +++ b/src/proc/asset/effect.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file effect.cpp + ** Implementation level functionality regarding the Asset representation of effects + ** @todo still unimplemented and stalled work as of 2016 + */ + + #include "proc/asset/effect.hpp" namespace proc { diff --git a/src/proc/asset/effect.hpp b/src/proc/asset/effect.hpp index fa9eed8fa..78ac74826 100644 --- a/src/proc/asset/effect.hpp +++ b/src/proc/asset/effect.hpp @@ -21,6 +21,11 @@ */ +/** @file effect.hpp + ** Definition of an Asset representation for any kind of _effect_ or media processor. + */ + + #ifndef ASSET_EFFECT_H #define ASSET_EFFECT_H diff --git a/src/proc/asset/inventory.hpp b/src/proc/asset/inventory.hpp index 1c86f7c9a..a0e34c119 100644 --- a/src/proc/asset/inventory.hpp +++ b/src/proc/asset/inventory.hpp @@ -21,6 +21,13 @@ */ +/** @file inventory.hpp + ** Exposing an ID registration cluster as a Meta Asset + ** @todo implementation draft from 2010, stalled as of 2016, + ** but likely to be of relevance eventually... + */ + + #ifndef ASSET_INVENTORY_H #define ASSET_INVENTORY_H diff --git a/src/proc/asset/media.cpp b/src/proc/asset/media.cpp index 8a35e6cab..f1d236bcf 100644 --- a/src/proc/asset/media.cpp +++ b/src/proc/asset/media.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file media.cpp + ** Implementation regarding the Media Asset abstraction + */ + + #include "lib/error.hpp" #include "proc/common.hpp" #include "proc/assetmanager.hpp" diff --git a/src/proc/asset/media.hpp b/src/proc/asset/media.hpp index 9f3e61729..a39b8647e 100644 --- a/src/proc/asset/media.hpp +++ b/src/proc/asset/media.hpp @@ -22,7 +22,7 @@ /** @file media.hpp - ** Media data is a specific kind of Asset. + ** Media data represented a specific kind of Asset. ** For the different kinds of Assets, we use sub-interfaces inheriting ** from the general Asset interface. To be able to get asset::Media instances ** directly from the AssetManager, we define a specialisation of the Asset ID. diff --git a/src/proc/asset/meta.cpp b/src/proc/asset/meta.cpp index a62cdfd5e..e2dfe40f5 100644 --- a/src/proc/asset/meta.cpp +++ b/src/proc/asset/meta.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file meta.cpp + ** Implementation details regarding the Meta Asset category + */ + + #include "proc/assetmanager.hpp" #include "proc/asset/meta.hpp" #include "lib/util.hpp" diff --git a/src/proc/asset/meta/time-grid.cpp b/src/proc/asset/meta/time-grid.cpp index a56e89b5e..4c374e573 100644 --- a/src/proc/asset/meta/time-grid.cpp +++ b/src/proc/asset/meta/time-grid.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file time-grid.cpp + ** Implementation of access to time-quantised reference scales + */ + + #include "proc/asset/meta/time-grid.hpp" #include "proc/asset/struct-scheme.hpp" #include "proc/assetmanager.hpp" @@ -73,7 +78,7 @@ namespace meta { * smart-ptr-to-Quantiser to that, which then can be * published via the \link advice.hpp "advice system"\endlink * @note this allows to use a time grid just "by name", - * without explicit dependance to the Session / Assets + * without explicit dependence to the Session / Assets */ inline PGrid publishWrapped (TimeGrid& newGrid) diff --git a/src/proc/asset/pipe.cpp b/src/proc/asset/pipe.cpp index f66b0ca53..5380a7ec5 100644 --- a/src/proc/asset/pipe.cpp +++ b/src/proc/asset/pipe.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file pipe.cpp + ** Implementation details regarding the Asset representation of a processing Pipe + */ + + #include "proc/asset/pipe.hpp" #include "proc/assetmanager.hpp" #include "lib/util.hpp" diff --git a/src/proc/asset/pipe.hpp b/src/proc/asset/pipe.hpp index 082aa7164..eb89ea964 100644 --- a/src/proc/asset/pipe.hpp +++ b/src/proc/asset/pipe.hpp @@ -21,6 +21,15 @@ */ +/** @file pipe.hpp + ** A "processing pipe" represented as Asset. + ** The Pipe Asset, especially the ID plays a crucial role within the + ** Session model to represent both attachment points for further media processors + ** and connection designations, which will be resolved to some input/output port + ** during the Builder run. + */ + + #ifndef ASSET_PIPE_H #define ASSET_PIPE_H diff --git a/src/proc/asset/preview.cpp b/src/proc/asset/preview.cpp index c27879f02..bce74421c 100644 --- a/src/proc/asset/preview.cpp +++ b/src/proc/asset/preview.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file preview.cpp + ** Implementation details regarding a placeholder / "Proxy" / preview media asset + */ + + #include "proc/asset/preview.hpp" namespace proc { diff --git a/src/proc/asset/preview.hpp b/src/proc/asset/preview.hpp index f576e1de2..a09562b83 100644 --- a/src/proc/asset/preview.hpp +++ b/src/proc/asset/preview.hpp @@ -21,6 +21,11 @@ */ +/** @file preview.hpp + ** Placeholder "proxy" Asset + */ + + #ifndef ASSET_PREVIEW_H #define ASSET_PREVIEW_H diff --git a/src/proc/asset/proc.cpp b/src/proc/asset/proc.cpp index 54bbde451..84242787c 100644 --- a/src/proc/asset/proc.cpp +++ b/src/proc/asset/proc.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file proc.cpp + ** Implementation details regarding the Asset representation of a media processing facility + */ + + #include "proc/assetmanager.hpp" #include "proc/asset/proc.hpp" #include "lib/util.hpp" diff --git a/src/proc/asset/procpatt.cpp b/src/proc/asset/procpatt.cpp index 38bcc2275..3de87b1fe 100644 --- a/src/proc/asset/procpatt.cpp +++ b/src/proc/asset/procpatt.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file procpatt.cpp + ** Implementation details related to "processing pattern" assets. + */ + + #include "proc/asset/procpatt.hpp" #include "proc/asset/proc.hpp" #include "proc/assetmanager.hpp" diff --git a/src/proc/asset/procpatt.hpp b/src/proc/asset/procpatt.hpp index b6202085a..c692d6fb8 100644 --- a/src/proc/asset/procpatt.hpp +++ b/src/proc/asset/procpatt.hpp @@ -21,6 +21,14 @@ */ +/** @file procpatt.hpp + ** Definition of a [structural asset](\ref struct.hpp) to express patterns of wiring or processing + ** Processing patterns can be seen as some kind of "micro code" (or macro code, if you prefer this + ** view angle), which will be executed within the machinery to wire and configure the render nodes + ** network, based on the objects in the Session model. + */ + + #ifndef ASSET_PROCPATT_H #define ASSET_PROCPATT_H diff --git a/src/proc/asset/sequence.cpp b/src/proc/asset/sequence.cpp index 88735f3a6..a5662e419 100644 --- a/src/proc/asset/sequence.cpp +++ b/src/proc/asset/sequence.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file sequence.cpp + ** Implementation parts of the Sequence entity within the Session model + */ + + #include "proc/asset/sequence.hpp" //#include "proc/mobject/session/fork.hpp" #include "proc/assetmanager.hpp" diff --git a/src/proc/asset/sequence.hpp b/src/proc/asset/sequence.hpp index 803995819..6e9ba7298 100644 --- a/src/proc/asset/sequence.hpp +++ b/src/proc/asset/sequence.hpp @@ -42,6 +42,10 @@ ** on the name-ID of the sequence: \c Struct::retrieve(Query ("id(theName).")) ** Additionally, a specific fork root may be requested: \c "id(theName),rootFork(trackID)." ** + ** @todo this is a very crucial part of the emerging design of the session model. Unfortunately, + ** development on that frontier has stalled since 2010, since we focused efforts towards + ** the player, the engine and the GUI lately (as of 2016) + ** ** @see Session ** @see StructFactory ** diff --git a/src/proc/asset/struct.cpp b/src/proc/asset/struct.cpp index 786be0299..d0aa7836d 100644 --- a/src/proc/asset/struct.cpp +++ b/src/proc/asset/struct.cpp @@ -21,6 +21,22 @@ * *****************************************************/ +/** @file struct.cpp + ** Implementation functions to support the "structural asset" abstraction. + ** This translation unit defines some functions of high importance for querying + ** and self-discovery of model parts. Moreover, it drives explicit template specialisations + ** for the core functions of the StructFacotry. + ** + ** # Vision + ** The vision is to express knowledge, configuration and some flexible parts of the model construction + ** through predicate rules. To support this vision, at various places within the translation from + ** Session model to render node network, a _query_ is used instead of hard wired functionality. + ** @todo while most code here is a very preliminary draft (let's call it a hack), as of 2016 + ** we acknowledge that this design is here to stay and represents one of the most + ** distinctive features of Lumiera + */ + + #include "proc/asset/struct.hpp" #include "proc/assetmanager.hpp" #include "proc/config-resolver.hpp" diff --git a/src/proc/asset/struct.hpp b/src/proc/asset/struct.hpp index 56b54f271..4ec18a145 100644 --- a/src/proc/asset/struct.hpp +++ b/src/proc/asset/struct.hpp @@ -22,9 +22,10 @@ /** @file struct.hpp + ** Asset representation of structural elements within the model. ** Structural parts of the Session (e.g. "tracks", i.e. Fork objects) can be ** reflected into the "bookkeeping view" as a specific Kind of Asset. - ** For the different \em kinds of Assets, we use sub-interfaces inheriting + ** For the different _kinds of Assets_, we use sub-interfaces inheriting ** from the general Asset interface, each of which expose a distinguishing feature. ** In the case of structural assets, the key point is the ability to retrieve an ** instance based on a capabilities query; structural assets are typically created @@ -36,7 +37,8 @@ ** - "tracks" are implemented as Fork represented as \c entryID within the asset view. ** - ProcPatt is used as a blueprint in the build process, a standard connection pattern ** - ** \par access and creation + ** ## access and creation + ** ** asset::Struct instances are created on demand; the interface is to invoke the ** StructFactory with a (typed) Query describing properties or capabilities. ** In case this query succeeds, an existing asset will be returned, otherwise diff --git a/src/proc/asset/timeline.cpp b/src/proc/asset/timeline.cpp index bf34d4f44..49c9ae395 100644 --- a/src/proc/asset/timeline.cpp +++ b/src/proc/asset/timeline.cpp @@ -21,10 +21,12 @@ * *****************************************************/ +/** @file timeline.cpp + ** Implementation functions of the Timeline entity within the Session model + */ + + #include "proc/asset/timeline.hpp" -//#include "proc/mobject/session/fork.hpp" -//#include "proc/mobject/placement.hpp" -//#include "proc/mobject/session/mobjectfactory.hpp" #include "proc/mobject/session/binding.hpp" #include "proc/assetmanager.hpp" diff --git a/src/proc/asset/typed-id.hpp b/src/proc/asset/typed-id.hpp index f3bd31763..56c83f902 100644 --- a/src/proc/asset/typed-id.hpp +++ b/src/proc/asset/typed-id.hpp @@ -33,6 +33,8 @@ ** the interfaces. Ichthyo expects this registration service to play a crucial role ** when it comes to integrating a real resolution engine (prolog). For now, the ** only interesting point is how to handle the automatic registration. + ** @todo and as of 2016, we acknowledge the importance of this approach, + ** just the topic is deferred for now and will be picked up later... ** ** @see configrules.hpp ** @see typed-lookup.cpp corresponding implementation diff --git a/src/proc/asset/typed-lookup.cpp b/src/proc/asset/typed-lookup.cpp index 942090b04..3754756bc 100644 --- a/src/proc/asset/typed-lookup.cpp +++ b/src/proc/asset/typed-lookup.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file typed-lookup.cpp + ** Implementation backend for a registration service to associate IDs, types and object instances + ** @todo this is placeholder code for an important facility, required once we engage into + ** predicate rules based configuration. For now (as of 2016), efforts towards this important + ** goal have been postponed, because we have to focus on a working engine first + */ + + #include "proc/asset/typed-id.hpp" diff --git a/src/proc/asset/unknown.cpp b/src/proc/asset/unknown.cpp index 131004e4f..7f6af5083 100644 --- a/src/proc/asset/unknown.cpp +++ b/src/proc/asset/unknown.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file unknown.cpp + ** Implementation functions regarding a marker asset for unknown media. + */ + + #include "proc/asset/unknown.hpp" #include "lib/format-string.hpp" diff --git a/src/proc/asset/unknown.hpp b/src/proc/asset/unknown.hpp index 54f234c71..9f588030d 100644 --- a/src/proc/asset/unknown.hpp +++ b/src/proc/asset/unknown.hpp @@ -21,6 +21,14 @@ */ +/** @file unknown.hpp + ** Marker Asset to indicate an unknown media source. + ** Elements marked as Unknown are retained in disabled state within the model. + ** This allows to open and work on a session file, without having all of the + ** data, setup or environment available + */ + + #ifndef ASSET_UNKNOWN_H #define ASSET_UNKNOWN_H diff --git a/src/proc/asset/viewer.cpp b/src/proc/asset/viewer.cpp index 7c78f0754..f111cdab7 100644 --- a/src/proc/asset/viewer.cpp +++ b/src/proc/asset/viewer.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file viewer.cpp + ** Implementation functions to represent a viewer or viewer attachment point. + ** @todo half finished draft, topic was postponed as of 2014, but will become relevant again + */ + + #include "proc/asset/viewer.hpp" //#include "proc/mobject/session/fork.hpp" //#include "proc/mobject/placement.hpp" diff --git a/src/proc/assetmanager.cpp b/src/proc/assetmanager.cpp index 48fc92d1b..9b7c8a2fa 100644 --- a/src/proc/assetmanager.cpp +++ b/src/proc/assetmanager.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file assetmanager.cpp + ** Implementation of Asset lookup and organisation functions + */ + + #include "proc/assetmanager.hpp" #include "proc/asset/db.hpp" diff --git a/src/proc/config-resolver.cpp b/src/proc/config-resolver.cpp index d7cb64575..ffd865fb3 100644 --- a/src/proc/config-resolver.cpp +++ b/src/proc/config-resolver.cpp @@ -1,4 +1,3 @@ - /* ConfigResolver - concrete setup for rule based configuration @@ -22,6 +21,14 @@ * *****************************************************/ +/** @file config-resolver.cpp + ** Implementation of bindings between Proc-Layer objects and rules-based configuration. + ** @todo draft from the early design phase of the Lumiera application. As of 2016, nothing + ** was done on behalf of rules-based configuration, other then preparing the whole architecture + ** for this capability. So this remains one of the most relevant goals of the Project. + */ + + #include "lib/error.hpp" #include "proc/config-resolver.hpp" #include "proc/mobject/session/query/fake-configrules.hpp" diff --git a/src/proc/control/argument-erasure.hpp b/src/proc/control/argument-erasure.hpp index 6d74bdf9a..6345849d1 100644 --- a/src/proc/control/argument-erasure.hpp +++ b/src/proc/control/argument-erasure.hpp @@ -21,6 +21,12 @@ */ +/** @file argument-erasure.hpp + ** Implementation helper to bind Proc-Layer commands with arbitrary argument tuples + ** @internal details of the [command handling framework](\ref command.hpp). + */ + + #ifndef CONTROL_ARGUMENT_ERASURE_H #define CONTROL_ARGUMENT_ERASURE_H diff --git a/src/proc/control/handling-pattern.cpp b/src/proc/control/handling-pattern.cpp index 032069d74..da1188175 100644 --- a/src/proc/control/handling-pattern.cpp +++ b/src/proc/control/handling-pattern.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file handling-pattern.cpp + ** Implementation of pre-defined command handling patterns + ** @internal detail of the Proc-Layer command handling framework. + */ + + #include "lib/error.hpp" #include "proc/control/handling-pattern.hpp" diff --git a/src/proc/control/mediaimpllib.hpp b/src/proc/control/media-impl-lib.hpp similarity index 60% rename from src/proc/control/mediaimpllib.hpp rename to src/proc/control/media-impl-lib.hpp index e01e3dcb2..08496ca30 100644 --- a/src/proc/control/mediaimpllib.hpp +++ b/src/proc/control/media-impl-lib.hpp @@ -1,5 +1,5 @@ /* - MEDIAIMPLLIB.hpp - interface providing a facade to an media handling library + MEDIA-IMPL-LIB.hpp - facade interface to access an external media handling library Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -21,8 +21,20 @@ */ -#ifndef CONTROL_MEDIAIMPLLIB_H -#define CONTROL_MEDIAIMPLLIB_H +/** @file media-impl-lib.hpp + ** Abstraction to represent (metadata) of an external library to handle media data + ** Lumiera delegates most actual media data processing to well established external + ** libraries. While configuring the render process, a [stream type](streamtype.hpp) + ** framework is used to gain uniform access to heterogeneous media and processing + ** facilities. At some point, we need to integrate the individual capabilities of + ** the referenced libraries, though. This will be done with adapter implementations, + ** where the interface MediaImplLip defines those aspects actually used and required + ** by our internal processing. + */ + + +#ifndef PROC_CONTROL_MEDIA_IMPL_LIB_H +#define PROC_CONTROL_MEDIA_IMPL_LIB_H #include "proc/streamtype.hpp" @@ -52,4 +64,4 @@ namespace control { }} // namespace proc::control -#endif +#endif /*PROC_CONTROL_MEDIA_IMPL_LIB_H*/ diff --git a/src/proc/control/pathmanager.cpp b/src/proc/control/pathmanager.cpp index 17870694a..46d97ff64 100644 --- a/src/proc/control/pathmanager.cpp +++ b/src/proc/control/pathmanager.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file pathmanager.cpp + ** Implementation functionality regarding decision about the proper + ** wiring and calculation strategy for rendering. + ** @todo placeholder as of 2014, development in this area is stalled + */ + + #include "proc/control/pathmanager.hpp" namespace proc { diff --git a/src/proc/control/pathmanager.hpp b/src/proc/control/pathmanager.hpp index 1c0e11722..f925bc7e6 100644 --- a/src/proc/control/pathmanager.hpp +++ b/src/proc/control/pathmanager.hpp @@ -21,6 +21,15 @@ */ +/** @file pathmanager.hpp + ** Facility to decide upon the actual render strategy. + ** When wiring the various processing facilities to form a render nodes network, + ** at times there are multiple possibilities to reach a given goal. This opens + ** the opportunity for optimisation and to configure specific variants or flavours. + ** @todo this is a design draft and just defines a placeholder to indicate our plans. + */ + + #ifndef CONTROL_PATHMANAGER_H #define CONTROL_PATHMANAGER_H diff --git a/src/proc/control/stypemanager.cpp b/src/proc/control/stypemanager.cpp index dbaa8e42b..2fce854b9 100644 --- a/src/proc/control/stypemanager.cpp +++ b/src/proc/control/stypemanager.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file stypemanager.cpp + ** Implementation functions of the stream type system + */ + + #include "proc/common.hpp" #include "proc/control/stypemanager.hpp" #include "proc/control/styperegistry.hpp" diff --git a/src/proc/control/stypemanager.hpp b/src/proc/control/stypemanager.hpp index 91952ff1d..1706aece5 100644 --- a/src/proc/control/stypemanager.hpp +++ b/src/proc/control/stypemanager.hpp @@ -21,6 +21,13 @@ */ +/** @file stypemanager.hpp + ** Interface to the stream type system + ** @todo very crucial part of the design, + ** unfortunately development in this area is stalled since 2012 + */ + + #ifndef PROC_CONTROL_STYPEMANAGER_H #define PROC_CONTROL_STYPEMANAGER_H diff --git a/src/proc/controllerfacade.cpp b/src/proc/controllerfacade.cpp deleted file mode 100644 index 84076b44e..000000000 --- a/src/proc/controllerfacade.cpp +++ /dev/null @@ -1,32 +0,0 @@ -/* - ControllerFacade - Facade and service access point for the Proc Layer Controller - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/controllerfacade.hpp" - -namespace proc_interface { - - /** */ - - - -} // namespace proc_interface diff --git a/src/proc/controllerfacade.hpp b/src/proc/controllerfacade.hpp index e7f2c95c2..b4e8babc4 100644 --- a/src/proc/controllerfacade.hpp +++ b/src/proc/controllerfacade.hpp @@ -21,6 +21,12 @@ */ +/** @file controllerfacade.hpp + ** unfinished draft for a "Proc-Layer Controller" + ** @todo as of 2016 it very much looks like there wont'be any such thing... + */ + + #ifndef PROC_INTERFACE_CONTROLLERFACADE_H #define PROC_INTERFACE_CONTROLLERFACADE_H diff --git a/src/proc/engine/buffer-local-key.hpp b/src/proc/engine/buffer-local-key.hpp index 5f93d1aaa..ac2b266d2 100644 --- a/src/proc/engine/buffer-local-key.hpp +++ b/src/proc/engine/buffer-local-key.hpp @@ -21,6 +21,11 @@ */ +/** @file buffer-local-key.hpp + ** A marker data type used in metadata / buffer management of the render engine. + */ + + #ifndef PROC_ENGINE_BUFFR_LOCAL_KEY_H #define PROC_ENGINE_BUFFR_LOCAL_KEY_H diff --git a/src/proc/engine/buffer-provider.cpp b/src/proc/engine/buffer-provider.cpp index e4224556a..9a25711a8 100644 --- a/src/proc/engine/buffer-provider.cpp +++ b/src/proc/engine/buffer-provider.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file buffer-provider.cpp + ** Implementation details related to buffer lifecycle management in the render engine. + */ + + #include "lib/error.hpp" #include "proc/engine/buffer-provider.hpp" #include "proc/engine/buffer-metadata.hpp" diff --git a/src/proc/engine/bufftable-obsolete.hpp b/src/proc/engine/bufftable-obsolete.hpp index 665726804..7cb1b17ba 100644 --- a/src/proc/engine/bufftable-obsolete.hpp +++ b/src/proc/engine/bufftable-obsolete.hpp @@ -21,6 +21,12 @@ */ +/** @file bufftable-obsolete.hpp + ** @deprecated obsolete since 2009, left in tree to keep some likewise unfinished code alive. + ** @see nodeinvocation.hpp + */ + + #ifndef ENGINE_BUFFHTABLE_OBSOLETE_H #define ENGINE_BUFFHTABLE_OBSOLETE_H diff --git a/src/proc/engine/bufftable.hpp b/src/proc/engine/bufftable.hpp index 14ea61977..a0f1289f8 100644 --- a/src/proc/engine/bufftable.hpp +++ b/src/proc/engine/bufftable.hpp @@ -21,6 +21,15 @@ */ +/** @file bufftable.hpp + ** helper for organisation of render data buffers + ** Used during the process of _"pulling"_ a render node, which recursively might + ** pull further nodes. Any node has a _render calculation function,_ which in turn + ** needs input and output buffers + ** @see buffer-provider.hpp + */ + + #ifndef ENGINE_BUFFHTABLE_H #define ENGINE_BUFFHTABLE_H diff --git a/src/proc/engine/calc-plan-continuation.cpp b/src/proc/engine/calc-plan-continuation.cpp index 9c72a0629..84aaaa463 100644 --- a/src/proc/engine/calc-plan-continuation.cpp +++ b/src/proc/engine/calc-plan-continuation.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file calc-plan-continuation.cpp + ** Implementation elements of render process planning. + ** @todo a draft created in 2013 and then stalled. This is not obsolete. + */ + + #include "proc/engine/calc-plan-continuation.hpp" #include "proc/engine/frame-coord.hpp" #include "proc/engine/job-ticket.hpp" diff --git a/src/proc/engine/calc-plan-continuation.hpp b/src/proc/engine/calc-plan-continuation.hpp index 47f8388ac..ba45ca6c1 100644 --- a/src/proc/engine/calc-plan-continuation.hpp +++ b/src/proc/engine/calc-plan-continuation.hpp @@ -21,6 +21,18 @@ */ +/** @file calc-plan-continuation.hpp + ** A specialised render job to care for the planning of the calculation process itself. + ** Rendering is seen as an open-ended, ongoing process, and thus the management and planning + ** of the render process itself is performed chunk wise and embedded into the other rendering + ** calculations. The _"rendering-as-it-is-planned-right-now"_ can be represented as a closure + ** to the jobs, which perform and update this plan on the go. And in fact, the head of the + ** calculation process, the CalcStream, holds onto such a closure to access current planning. + ** + ** @todo a draft created in 2013 and then stalled. This is not obsolete. + */ + + #ifndef PROC_ENGINE_CALC_PLAN_CONTINUATION_H #define PROC_ENGINE_CALC_PLAN_CONTINUATION_H diff --git a/src/proc/engine/calc-stream.hpp b/src/proc/engine/calc-stream.hpp index 3b7ae9b2d..b39b89a75 100644 --- a/src/proc/engine/calc-stream.hpp +++ b/src/proc/engine/calc-stream.hpp @@ -21,6 +21,25 @@ */ +/** @file calc-stream.hpp + ** A core abstraction within the render engine to represent an ongoing calculation. + ** Within the Lumiera render engine, the rendering process is modelled in a functional way, + ** as a _stream of calculations_ -- which eventually result in a stream of data frames. + ** Typically, streams in this context are conceived as unlimited and open-ended, and + ** can be represented by a generator or continuation function. Moreover, the invocation + ** of this "continue-the-stream"-function is embedded into the other rendering calculations + ** as a series of planning jobs. Whose purpose is, to create further future calculation jobs, + ** including future planning jobs. + ** + ** All of this structure thus exists only dynamically, always in ongoing evaluation. + ** For the interface level we thus create a symbolic placeholder, the CalcStream object + ** + ** @see engine-service.hpp + ** @todo this draft was created in 2013 just to the point of defining the skeleton of the engine. + ** @todo as of 2016, this is considered the way to go and will be completed _eventually_ + */ + + #ifndef PROC_ENGINE_CALC_STREAM_H #define PROC_ENGINE_CALC_STREAM_H @@ -138,6 +157,5 @@ namespace engine{ -} // namespace engine -} // namespace proc -#endif +}}// namespace proc::engine +#endif /*PROC_ENGINE_CALC_STREAM_H*/ diff --git a/src/proc/engine/diagnostic-buffer-provider.cpp b/src/proc/engine/diagnostic-buffer-provider.cpp index 3258e2f86..53123b640 100644 --- a/src/proc/engine/diagnostic-buffer-provider.cpp +++ b/src/proc/engine/diagnostic-buffer-provider.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file diagnostic-buffer-provider.cpp + ** Implementation details of unit test support regarding internals of the render engine. + ** + ** @todo WIP from 2013, half finished, stalled + ** @see buffer-provider-protocol-test.cpp + */ + + #include "lib/error.hpp" #include "lib/meta/function.hpp" diff --git a/src/proc/engine/diagnostic-buffer-provider.hpp b/src/proc/engine/diagnostic-buffer-provider.hpp index fcb453fd9..f38d4bf6f 100644 --- a/src/proc/engine/diagnostic-buffer-provider.hpp +++ b/src/proc/engine/diagnostic-buffer-provider.hpp @@ -22,7 +22,7 @@ /** @file diagnostic-buffer-provider.hpp ** A facility for writing unit-tests targeting the BufferProvider interface. - ** + ** ** @see buffer-provider-protocol-test.cpp */ diff --git a/src/proc/engine/dispatch-table.cpp b/src/proc/engine/dispatch-table.cpp index ef92d2236..e7b603df0 100644 --- a/src/proc/engine/dispatch-table.cpp +++ b/src/proc/engine/dispatch-table.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file dispatch-table.cpp + ** Implementation details of render job generation. + ** @todo draft from 2011, stalled, relevance not yet clear + */ + + #include "proc/engine/dispatch-table.hpp" //#include "lib/frameid.hpp" //#include "proc/state.hpp" diff --git a/src/proc/engine/dispatch-table.hpp b/src/proc/engine/dispatch-table.hpp index 57b3324e7..cf34825b5 100644 --- a/src/proc/engine/dispatch-table.hpp +++ b/src/proc/engine/dispatch-table.hpp @@ -21,6 +21,12 @@ */ +/** @file dispatch-table.hpp + ** Implementation details of render job generation. + ** @todo draft from 2011, stalled, relevance not yet clear + */ + + #ifndef PROC_ENGINE_DISPATCH_TABLE_H #define PROC_ENGINE_DISPATCH_TABLE_H diff --git a/src/proc/engine/dispatcher.cpp b/src/proc/engine/dispatcher.cpp index f79042c9e..0c160f0f2 100644 --- a/src/proc/engine/dispatcher.cpp +++ b/src/proc/engine/dispatcher.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file dispatcher.cpp + ** Implementation parts of job generation within an ongoing render process + ** @todo valid draft, unfortunately stalled in 2013 + */ + + #include "proc/engine/dispatcher.hpp" //#include "lib/frameid.hpp" //#include "proc/state.hpp" @@ -34,7 +40,7 @@ namespace engine { FrameSequencer::~FrameSequencer() { } - /** */ + /** @todo WIP */ Dispatcher::JobBuilder Dispatcher::onCalcStream (ModelPort modelPort, uint channel) { @@ -43,7 +49,7 @@ namespace engine { } - /** */ + /** @todo WIP */ FrameCoord Dispatcher::JobBuilder::relativeFrameLocation (TimeAnchor& refPoint, FrameCnt frameOffset) { diff --git a/src/proc/engine/dispatcher.hpp b/src/proc/engine/dispatcher.hpp index 91d2d0ce6..9065ad0c4 100644 --- a/src/proc/engine/dispatcher.hpp +++ b/src/proc/engine/dispatcher.hpp @@ -21,6 +21,17 @@ */ +/** @file dispatcher.hpp + ** Service abstraction within the render engine for generating render jobs. + ** On interface level, the render engine uses the notion of a [calculation stream](CalcStream) + ** to represent an ongoing rendering process. Within the _implementation_ of such a process, + ** the Dispatcher is responsible for transforming the generic setup of such a calculation stream + ** into a sequence of concrete jobs, anchored at some distinct point in time. + ** + ** @todo valid draft, unfortunately stalled in 2013 + */ + + #ifndef PROC_ENGINE_DISPATCHER_H #define PROC_ENGINE_DISPATCHER_H @@ -57,7 +68,7 @@ namespace engine { * evaluation and planning of new jobs, which can then be handed over to the Scheduler * for time-bound activation. * - * \par usage considerations + * ## usage considerations * the asynchronous and ongoing nature of the render process mandates to avoid a central * instance for operating this planning process. Instead, together with each chunk of * planned jobs we generate a continuation job, which -- on activation -- will pick up diff --git a/src/proc/engine/engine-service-mock.cpp b/src/proc/engine/engine-service-mock.cpp index aa4f2a1b4..8fd7e96fa 100644 --- a/src/proc/engine/engine-service-mock.cpp +++ b/src/proc/engine/engine-service-mock.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file engine-service-mock.cpp + ** Implementation translation unit for a mock render engine for unit testing. + ** @todo draft from 2012, and, while stalled, still relevant as of 2016 + */ + + #include "proc/engine/engine-service-mock.hpp" #include "proc/engine/worker/dummy-tick.hpp" diff --git a/src/proc/engine/engine-service.cpp b/src/proc/engine/engine-service.cpp index a31292fd8..7269e541e 100644 --- a/src/proc/engine/engine-service.cpp +++ b/src/proc/engine/engine-service.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file engine-service.cpp + ** Implementation parts related to the engine service abstraction + */ + + #include "proc/engine/engine-service.hpp" #include "lib/itertools.hpp" diff --git a/src/proc/engine/engine-service.hpp b/src/proc/engine/engine-service.hpp index 92642d5c9..d653d6974 100644 --- a/src/proc/engine/engine-service.hpp +++ b/src/proc/engine/engine-service.hpp @@ -34,11 +34,12 @@ ** these jobs are to be executed through the scheduler in the backend layer. ** ** While the individual CalcStram is simple, linear and unmodifiable, any CalcStream may be - ** \em superseded by a new definition. In this case, the engine will care for a seamless + ** _superseded_ by a new definition. In this case, the engine will care for a seamless ** switch and continuation; under the hood, there is a mechanism to discard resources ** tied to the original CalcStream, once the switch to the new definition is complete. ** ** @ingroup engine + ** @todo draft from 2013, stalled, but still relevant and to be continued eventually ** @see EngineInterface_test ** @see CalcStream_test ** @see proc::play::PlayerService @@ -174,6 +175,5 @@ namespace engine{ -} // namespace engine -} // namespace proc -#endif +}} // namespace proc::engine +#endif /*PROC_ENGINE_ENGINE_SERVICE_H*/ diff --git a/src/proc/engine/frame-coord.hpp b/src/proc/engine/frame-coord.hpp index 49a9550c5..cc6f5a940 100644 --- a/src/proc/engine/frame-coord.hpp +++ b/src/proc/engine/frame-coord.hpp @@ -21,6 +21,11 @@ */ +/** @file frame-coord.hpp + ** Tuple data type to address distinct frames within the render engine calculations. + */ + + #ifndef PROC_ENGINE_FRAME_COORD_H #define PROC_ENGINE_FRAME_COORD_H @@ -96,8 +101,8 @@ namespace engine { * This interface describes the essence of generating * a series of frame locations, which is necessary for * planning render jobs. To implement it, actually some - * kind of \link lib::time::Quantiser frame grid \endlink - * is necessary -- in practice we use a Dispatcher, which is + * kind of [frame grid](\ref lib::time::Quantiser) is + * necessary -- in practice we use a Dispatcher, which is * backed by the Segmentation (i.e. the render nodes network). */ class FrameSequencer diff --git a/src/proc/engine/job-ticket.hpp b/src/proc/engine/job-ticket.hpp index f3667eaa4..25330979a 100644 --- a/src/proc/engine/job-ticket.hpp +++ b/src/proc/engine/job-ticket.hpp @@ -21,6 +21,14 @@ */ +/** @file job-ticket.hpp + ** Execution plan to generate render jobs within a specific render process. + ** A JobTicket is a preconfigured generator for render jobs, which in turn + ** are functors to perform the calculations for a specific data frame. + ** @see job.hpp + */ + + #ifndef PROC_ENGINE_JOB_TICKET_H #define PROC_ENGINE_JOB_TICKET_H @@ -69,7 +77,7 @@ using util::isnil; * To turn a JobTicket into an actual job, we need the additional information * regarding the precise frame number (=nominal time) and the channel number * to calculate (in case the actual feed is multichannel, which is the default). - * This way, the JobTicket acts as higher order function: a function + * This way, the JobTicket acts as _higher order function:_ a function * generating on invocation another, specific function (= the job). * * @todo 1/12 WIP-WIP-WIP defining the invocation sequence and render jobs @@ -231,8 +239,8 @@ using util::isnil; JobTicket::startExploration() const { UNIMPLEMENTED ("somehow build a self-referential pseudo-prerequisite, and seed an ExplorationState with that"); - /////////////////////TODO problem is: we need an JobTicket::Prerequisite instance, where the descriptor points to "self" (this JobTicket) - /////////////////////TODO : but this instance needs to reside somewhere at a safe location, since we want to embed an LinkedElements-iterator + /////////////////////TODO problem is: we need a JobTicket::Prerequisite instance, where the descriptor points to "self" (this JobTicket) + /////////////////////TODO : but this instance needs to reside somewhere at a safe location, since we want to embed a LinkedElements-iterator /////////////////////TODO : into the ExplorationState. And obviously we do not want that instance in each JobTicket, only in the top level ones /////////////////////TODO : on second thought -- better have a top-level entry point to the evaluation of a frame diff --git a/src/proc/engine/link.cpp b/src/proc/engine/link.cpp deleted file mode 100644 index 0ee39458e..000000000 --- a/src/proc/engine/link.cpp +++ /dev/null @@ -1,35 +0,0 @@ -/* - Link - forwarding, adapting or connecting ProcNode - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/engine/link.hpp" - -namespace proc { -namespace engine - { - - /** */ - - - - - }} // namespace engine diff --git a/src/proc/engine/link.hpp b/src/proc/engine/link.hpp deleted file mode 100644 index ea9b17edb..000000000 --- a/src/proc/engine/link.hpp +++ /dev/null @@ -1,54 +0,0 @@ -/* - LINK.hpp - forwarding, adapting or connecting ProcNode - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -*/ - - -#ifndef ENGINE_LINK_H -#define ENGINE_LINK_H - -#include "proc/engine/procnode.hpp" - - - -namespace proc { -namespace engine { - - - /** - * Abstraction of all sorts of connecting Elements with - * special functionality. For example the coneections enabling - * to mix OpenGL implemented Effects/Previews with normal CPU based - * processing in one render pipeline. - */ - class Link : public ProcNode - { - Link (WiringDescriptor const& wd) - : ProcNode(wd) - { } - - ///////TODO: flatten hierarchy if we don't have common functionallity for all Link-Subclasses - ///////TODO: can be decdiede when we know more how to handle OpenGL rendering - }; - - - -}} // namespace proc::engine -#endif diff --git a/src/proc/engine/mask.cpp b/src/proc/engine/mask.cpp index b341f51b9..bb9750b61 100644 --- a/src/proc/engine/mask.cpp +++ b/src/proc/engine/mask.cpp @@ -21,14 +21,27 @@ * *****************************************************/ +/** @file mask.cpp + ** Mask generator node implementation + ** @deprecated not clear if needed as of 2016 + */ + + +#include "lib/error.hpp" #include "proc/engine/mask.hpp" namespace proc { namespace engine { - + + + Mask::Mask (WiringDescriptor const& wd) + : ProcNode(wd) + { + UNIMPLEMENTED("do we need a dedicated ProcNode subclass as mask generator?"); + } + /** */ - - - - -}} // namespace engine + + + +}}// namespace engine diff --git a/src/proc/engine/mask.hpp b/src/proc/engine/mask.hpp index 364f370a8..53637619d 100644 --- a/src/proc/engine/mask.hpp +++ b/src/proc/engine/mask.hpp @@ -21,23 +21,34 @@ */ -#ifndef ENGINE_MASK_H -#define ENGINE_MASK_H +/** @file mask.hpp + ** Specialised render node for generating mask (alpha channel) data. + ** @todo this file is there since the very first code generation steps at start + ** of the Lumiera project. It never became clear if a mask generator would + ** need to be a dedicated ProcNode subclass; but in fact the project did + ** not reach the point of implementing anything regarding that topic. + */ + + +#ifndef PROC_ENGINE_MASK_H +#define PROC_ENGINE_MASK_H #include "proc/engine/procnode.hpp" namespace proc { -namespace engine - { - - - class Mask : public ProcNode - {}; - - - - +namespace engine{ + + + class Mask + : public ProcNode + { + public: + Mask (WiringDescriptor const&); + }; + + + }} // namespace proc::engine -#endif +#endif /*PROC_ENGINE_MASK_H*/ diff --git a/src/proc/engine/nodefactory.cpp b/src/proc/engine/nodefactory.cpp index 5812bf40a..d36dfff2c 100644 --- a/src/proc/engine/nodefactory.cpp +++ b/src/proc/engine/nodefactory.cpp @@ -1,5 +1,5 @@ /* - NodeFactory - Interface for creating processing nodes of various kinds + NodeFactory - Service for creating processing nodes of various kinds Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file nodefactory.cpp + ** Implementation of render node setup and wiring + ** @todo draft from the early days of the Lumiera project, reworked in 2009 + ** Development activity in that area as stalled ever since. In the end, + ** it is highly likely we'll _indeed need_ a node factory though... + */ + + #include "proc/engine/nodefactory.hpp" #include "proc/mobject/session/effect.hpp" #include "lib/allocation-cluster.hpp" @@ -41,7 +49,10 @@ namespace engine { using mobject::session::Effect; - /** create a processing node able to render an effect */ + /** create a processing node able to render an effect + * @todo as of 2016 this is the only (placeholder) implementation + * to indicate how building and wiring of nodes was meant to happen + */ PNode NodeFactory::operator() (Placement const& effect, WiringSituation& intendedWiring) { diff --git a/src/proc/engine/nodefactory.hpp b/src/proc/engine/nodefactory.hpp index 63b5ca719..5782a898b 100644 --- a/src/proc/engine/nodefactory.hpp +++ b/src/proc/engine/nodefactory.hpp @@ -1,5 +1,5 @@ /* - NODEFACTORY.hpp - Interface for creating processing nodes of various kinds + NODEFACTORY.hpp - Service for creating processing nodes of various kinds Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -21,6 +21,14 @@ */ +/** @file nodefactory.hpp + ** A factory to build processing nodes + ** @todo draft from the early days of the Lumiera project, reworked in 2009 + ** Development activity in that area as stalled ever since. In the end, + ** it is highly likely we'll _indeed need_ a node factory though... + */ + + #ifndef ENGINE_NODEFACTORY_H #define ENGINE_NODEFACTORY_H diff --git a/src/proc/engine/nodeinvocation.hpp b/src/proc/engine/nodeinvocation.hpp index 18f1bb75e..196ddebeb 100644 --- a/src/proc/engine/nodeinvocation.hpp +++ b/src/proc/engine/nodeinvocation.hpp @@ -35,13 +35,15 @@ ** Invocation object (a sub-interface of StateAdapter) to access the various aspects of the ** invocation state. ** - ** \par composition of the Invocation State + ** ## composition of the Invocation State + ** ** For each individual ProcNode#pull() call, the WiringAdapter#callDown() builds an StateAdapter ** instance directly on the stack, managing the actual buffer pointers and state references. Using this ** StateAdapter, the predecessor nodes are pulled. The way these operations are carried out is encoded ** in the actual StateAdapter type known to the NodeWiring (WiringAdapter) instance. All of these actual ** StateAdapter types are built as implementing the engine::State interface. - ** + ** + ** @todo relies still on an [obsoleted implementation draft](\ref bufftable-obsolete.hpp) ** @see engine::ProcNode ** @see engine::StateProxy ** @see engine::BuffTable diff --git a/src/proc/engine/nodewiring.cpp b/src/proc/engine/nodewiring.cpp index c6d596ba0..7a837352e 100644 --- a/src/proc/engine/nodewiring.cpp +++ b/src/proc/engine/nodewiring.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file nodewiring.cpp + ** Implementation of node wiring to build a render node network + ** @todo unfinished draft from 2009 regarding the render process + */ + + #include "proc/engine/procnode.hpp" #include "proc/engine/nodewiring.hpp" #include "proc/engine/nodeoperation.hpp" diff --git a/src/proc/engine/nodewiring.hpp b/src/proc/engine/nodewiring.hpp index 3eb3172cb..ef3692e4b 100644 --- a/src/proc/engine/nodewiring.hpp +++ b/src/proc/engine/nodewiring.hpp @@ -21,6 +21,12 @@ */ +/** @file nodewiring.hpp + ** Mechanism to wire ProcNode instances for a render network + ** @todo unfinished draft from 2009 regarding the render process + */ + + #ifndef ENGINE_NODEWIRING_H #define ENGINE_NODEWIRING_H diff --git a/src/proc/engine/pluginadapter.cpp b/src/proc/engine/pluginadapter.cpp deleted file mode 100644 index 5bbc144e8..000000000 --- a/src/proc/engine/pluginadapter.cpp +++ /dev/null @@ -1,34 +0,0 @@ -/* - PluginAdapter - Adapter for integrating various Effect processors in the render pipeline - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/engine/pluginadapter.hpp" - -namespace proc { -namespace engine { - - /** */ - - - - -}} // namespace engine diff --git a/src/proc/engine/pluginadapter.hpp b/src/proc/engine/pluginadapter.hpp deleted file mode 100644 index 38d7152a3..000000000 --- a/src/proc/engine/pluginadapter.hpp +++ /dev/null @@ -1,49 +0,0 @@ -/* - PLUGINADAPTER.hpp - Adapter for integrating various Effect processors in the render pipeline - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -*/ - - -#ifndef ENGINE_PLUGINADAPTER_H -#define ENGINE_PLUGINADAPTER_H - -#include "proc/engine/procnode.hpp" - - - -namespace proc { -namespace engine - { - - - /** - * Adapter used to integrate an effects processor in the render pipeline. - * Effects processors are typically defined in a separate library and - * will be loaded at runtime using Lumiera's plugin interface. - */ - class PluginAdapter : public ProcNode - { - ///////////// - }; - - - -}} // namespace proc::engine -#endif diff --git a/src/proc/engine/render-invocation.cpp b/src/proc/engine/render-invocation.cpp index adf7d67ac..8e0a39c86 100644 --- a/src/proc/engine/render-invocation.cpp +++ b/src/proc/engine/render-invocation.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file render-invocation.cpp + ** Implementation details regarding the invocation of a single render node + ** @deprecated very likely to happen in a different way, while the concept remains valid + ** @todo unfinished draft from 2009 regarding the render process + */ + + #include "proc/engine/render-invocation.hpp" #include "proc/engine/stateproxy.hpp" diff --git a/src/proc/engine/render-invocation.hpp b/src/proc/engine/render-invocation.hpp index deb2b27f7..8e3ae256e 100644 --- a/src/proc/engine/render-invocation.hpp +++ b/src/proc/engine/render-invocation.hpp @@ -23,7 +23,9 @@ /** @file render-invocation.hpp ** Initiate a single calculation unit within the renderengine. ** Usually, this will cause the rendering of a single frame or sub-frame. - ** + ** + ** @todo unfinished draft from 2009 regarding the render process + ** ** @see engine::ProcNode ** @see State ** @see node-basic-test.cpp @@ -47,7 +49,7 @@ namespace engine { /** - * TODO: type comment + * @todo write type comment */ class RenderInvocation { diff --git a/src/proc/engine/renderengine.cpp b/src/proc/engine/renderengine.cpp index 706a87e07..8cbdb7e21 100644 --- a/src/proc/engine/renderengine.cpp +++ b/src/proc/engine/renderengine.cpp @@ -21,12 +21,25 @@ * *****************************************************/ +/** @file renderengine.cpp + ** @deprecated a pile of crap, leftovers and started drafts, stalled since 2011 -- but maybe here to stay... + */ + + +#include "lib/error.hpp" #include "proc/engine/renderengine.hpp" namespace proc { namespace engine { + RenderEngine::RenderEngine() + : RenderGraph() + { + UNIMPLEMENTED("wtf... a video editor without implemented render engine??"); + } + + /** */ diff --git a/src/proc/engine/renderengine.hpp b/src/proc/engine/renderengine.hpp index abe036bef..ed533afdd 100644 --- a/src/proc/engine/renderengine.hpp +++ b/src/proc/engine/renderengine.hpp @@ -21,15 +21,20 @@ */ -#ifndef ENGINE_RENDERENGINE_H -#define ENGINE_RENDERENGINE_H +/** @file renderengine.hpp + ** (Planned) access point to the render engine as service. + ** @deprecated a pile of crap, leftovers and started drafts, stalled since 2011 -- but maybe here to stay... + */ -#include + +#ifndef PROC_ENGINE_RENDERENGINE_H +#define PROC_ENGINE_RENDERENGINE_H #include "proc/engine/rendergraph.hpp" +#include + -using std::list; /////////////////////////////TODO 7/11 this is a piece of debris, left over from the first attempt to complete the render nodes network. /////////////////////////////TODO Meanwhile the intention is to treat the render nodes network more like a data structure, @@ -40,20 +45,23 @@ using std::list; namespace proc { namespace engine { + using std::list; /** - * @todo this is planned to become the frontend + * @todo this was planned to become the frontend * to the render node network, which can be considered * at the lower end of the middle layer; the actual * render operations are mostly implemented by the backend * ////////TODO WIP as of 12/2010 */ - class RenderEngine : public RenderGraph + class RenderEngine + : public RenderGraph { public: ///// TODO: find out about the public operations // note: the play controller lives in the proc-layer, - // but is a subsystem separate of the sesison. + // but is a subsystem separate of the session. + RenderEngine(); private: list renderSegments; @@ -61,4 +69,4 @@ namespace engine { }; }} // namespace proc::engine -#endif +#endif /*PROC_ENGINE_RENDERENGINE_H*/ diff --git a/src/proc/engine/rendergraph.cpp b/src/proc/engine/rendergraph.cpp index 0c100fde3..b04f6686f 100644 --- a/src/proc/engine/rendergraph.cpp +++ b/src/proc/engine/rendergraph.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file rendergraph.cpp + ** @deprecated a pile of crap, leftovers and started drafts, stalled since 2011 -- but maybe here to stay... + */ + + #include "proc/engine/rendergraph.hpp" #include "lib/frameid.hpp" #include "proc/state.hpp" diff --git a/src/proc/engine/rendergraph.hpp b/src/proc/engine/rendergraph.hpp index 63c039e0f..50fe228de 100644 --- a/src/proc/engine/rendergraph.hpp +++ b/src/proc/engine/rendergraph.hpp @@ -21,8 +21,13 @@ */ -#ifndef ENGINE_RENDERGRAPH_H -#define ENGINE_RENDERGRAPH_H +/** @file rendergraph.hpp + ** @deprecated a pile of crap, leftovers and started drafts, stalled since 2011 -- but maybe here to stay... + */ + + +#ifndef PROC_ENGINE_RENDERGRAPH_H +#define PROC_ENGINE_RENDERGRAPH_H #include "proc/common.hpp" #include "proc/state.hpp" @@ -66,4 +71,4 @@ namespace engine { }} // namespace proc::engine -#endif +#endif /*PROC_ENGINE_RENDERGRAPH_H*/ diff --git a/src/proc/engine/source.cpp b/src/proc/engine/source.cpp index 477bc768e..d63ab9a72 100644 --- a/src/proc/engine/source.cpp +++ b/src/proc/engine/source.cpp @@ -21,15 +21,22 @@ * *****************************************************/ +/** @file source.cpp + ** Implementation of a source media reading render node. + */ + + #include "proc/engine/source.hpp" namespace proc { -namespace engine - { - +namespace engine { + + Source::Source (WiringDescriptor const& wd) + : ProcNode(wd) + { } + /** */ - - - - + + + }} // namespace engine diff --git a/src/proc/engine/source.hpp b/src/proc/engine/source.hpp index fedeb1784..8ec180103 100644 --- a/src/proc/engine/source.hpp +++ b/src/proc/engine/source.hpp @@ -21,6 +21,18 @@ */ +/** @file source.hpp + ** Processing node to read media data. + ** The render engine node network is activated by _"pulling"_ from the _exit nodes._ + ** Recursively, any rendering calculations will eventually hit a engine::Source node, + ** to retrieve existing (raw) media data + ** @todo this file is there since the very first code generation steps at start + ** of the Lumiera project. It is not yet clear if those source reading nodes + ** will indeed be ProcNode subclasses, or rather specifically configured + ** processing nodes... + */ + + #ifndef ENGINE_SOURCE_H #define ENGINE_SOURCE_H @@ -41,9 +53,7 @@ namespace engine */ class Source : public ProcNode { - Source (WiringDescriptor const& wd) - : ProcNode(wd) - { } + Source (WiringDescriptor const&); }; diff --git a/src/proc/engine/stateproxy.cpp b/src/proc/engine/stateproxy.cpp index c62a468a5..9fed46358 100644 --- a/src/proc/engine/stateproxy.cpp +++ b/src/proc/engine/stateproxy.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file stateproxy.cpp + ** Implementation details of some stateful operations needed from within the render calculation. + ** @todo unfinished draft from 2009 regarding the render process + */ + + #include "proc/engine/stateproxy.hpp" namespace proc { diff --git a/src/proc/engine/stateproxy.hpp b/src/proc/engine/stateproxy.hpp index 269e47dae..99fc5319b 100644 --- a/src/proc/engine/stateproxy.hpp +++ b/src/proc/engine/stateproxy.hpp @@ -21,6 +21,18 @@ */ +/** @file stateproxy.hpp + ** Access point to the state of a frame rendering evaluation. + ** The rendering of frames is triggered from a render job, and recursively + ** retrieves the data from predecessor nodes. Some statefull aspects are involved + ** into this recursive evaluation, beyond the data in the local call stack. Such + ** additional statefull dependencies are problematic (regarding concurrency and + ** throughput) and are thus abstracted from the actual processing operations + ** with the help of the proc::engine::State interface + ** @todo unfinished draft from 2009 regarding the render process + */ + + #ifndef ENGINE_STATEPROXY_H #define ENGINE_STATEPROXY_H diff --git a/src/proc/engine/time-anchor.hpp b/src/proc/engine/time-anchor.hpp index 2cded87ea..211f8860f 100644 --- a/src/proc/engine/time-anchor.hpp +++ b/src/proc/engine/time-anchor.hpp @@ -21,6 +21,18 @@ */ +/** @file time-anchor.hpp + ** Representation of a _continuation point_ for planning the render process. + ** In the Lumiera engine, render and playback processes are modelled as infinite streams, + ** which are evaluated chunk wise. The TimeAnchor is used to mark a point, where the + ** _planning_ of further render jobs will be picked up and continued later on + ** + ** @todo this is part of an implementation draft from 2013, + ** to create a complete outline of player and render job generation. + ** @todo as of 2016 this effort is stalled, but remains valid + */ + + #ifndef PROC_ENGINE_TIME_ANCHOR_H #define PROC_ENGINE_TIME_ANCHOR_H @@ -57,7 +69,7 @@ namespace engine { * the TimeAnchor closure is the definitive binding between the abstract logical time of the * session timeline, and the real wall-clock time forming the deadline for rendering. * - * \par internals + * ## internals * The time anchor associates a nominal time, defined on the implicit time grid * of some given Timings, with an actual wall clock time. Due to the usage situation, * the TimeAnchor takes on the secondary meaning of a breaking point; everything \em before diff --git a/src/proc/engine/tracking-heap-block-provider.cpp b/src/proc/engine/tracking-heap-block-provider.cpp index 3ca8d68d5..d3c8a885a 100644 --- a/src/proc/engine/tracking-heap-block-provider.cpp +++ b/src/proc/engine/tracking-heap-block-provider.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file tracking-heap-block-provider.cpp + ** Implementation details of a mock engine::BufferProvider for unit testing + */ + + #include "lib/error.hpp" #include "include/logging.h" //#include "lib/meta/function.hpp" diff --git a/src/proc/engine/worker/dummy-image-generator.cpp b/src/proc/engine/worker/dummy-image-generator.cpp index 577da2f94..e08c13d6a 100644 --- a/src/proc/engine/worker/dummy-image-generator.cpp +++ b/src/proc/engine/worker/dummy-image-generator.cpp @@ -22,6 +22,12 @@ * *****************************************************/ +/** @file dummy-image-generator.cpp + ** Implementation of a generator for dummy video frames for a mockup + ** @todo obsolete since 2010, can be removed once we have a real player in the UI + */ + + #include "proc/engine/worker/dummy-image-generator.hpp" diff --git a/src/proc/engine/worker/dummy-image-generator.hpp b/src/proc/engine/worker/dummy-image-generator.hpp index e364423ef..c9c00315f 100644 --- a/src/proc/engine/worker/dummy-image-generator.hpp +++ b/src/proc/engine/worker/dummy-image-generator.hpp @@ -29,6 +29,7 @@ ** by Joel within PlaybackController, then factored out into a separate ** dummy playback service. ** + ** @todo obsolete since 2010, can be removed once we have a real player in the UI ** @see gui::controller::PlaybackController ** @see proc::play::DummyPlayerService ** diff --git a/src/proc/external/libgavl.cpp b/src/proc/external/libgavl.cpp index 637e7c559..99864d482 100644 --- a/src/proc/external/libgavl.cpp +++ b/src/proc/external/libgavl.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file libgavl.cpp + ** Implementation details of using the GAVL library for processing + ** @todo 2016 evaluate if libGAVL is still active and maintained + */ + + #include "proc/common.hpp" #include "proc/external/libgavl.hpp" #include "proc/control/stypemanager.hpp" @@ -52,9 +58,9 @@ namespace external { /** * Use an type information struct, which actually has to be - * a GAVL frametype (TODO), to wire up an ImplFacade such + * a GAVL frame type (TODO), to wire up an ImplFacade such * as to deal with GAVL data frames of this type. - * @todo fill in the acutal GAVL frame type + * @todo fill in the actual GAVL frame type * @todo how to distinguish the audio and the video case? */ ImplFacadeGAVL const& diff --git a/src/proc/external/libgavl.hpp b/src/proc/external/libgavl.hpp index 632a76c66..1189c0abb 100644 --- a/src/proc/external/libgavl.hpp +++ b/src/proc/external/libgavl.hpp @@ -21,11 +21,20 @@ */ +/** @file libgavl.hpp + ** Concrete implementation of the MediaImplLib facade to work with `libGAVL` + ** @todo a draft and placeholder code from 2008, at which time the intention was + ** to rely on libGAVL for processing of raw media data. This seemed like a + ** good idea at that time, but we should re-evaluate if libGAVL is maintained + ** and in actual use, before we start really relying on it + */ + + #ifndef PROC_EXTERNAL_LIBGAVL_H #define PROC_EXTERNAL_LIBGAVL_H -#include "proc/control/mediaimpllib.hpp" +#include "proc/control/media-impl-lib.hpp" @@ -47,6 +56,7 @@ namespace external { * in an implementation agnostic way. * @note GAVL types are automagically registered into the * control::STypeManager on reset and thus are always available. + * @todo 2016 evaluate if libGAVL is still active and maintained */ class ImplFacadeGAVL : public ImplFacade diff --git a/src/proc/mobject/builder/assembler.cpp b/src/proc/mobject/builder/assembler.cpp index 3ea5a0bd7..4bce7ad07 100644 --- a/src/proc/mobject/builder/assembler.cpp +++ b/src/proc/mobject/builder/assembler.cpp @@ -21,19 +21,25 @@ * *****************************************************/ +/** @file assembler.cpp + ** @todo initially generated code of unclear relevance + */ + + +#include "lib/error.hpp" #include "proc/mobject/builder/assembler.hpp" namespace proc { namespace mobject { namespace builder { - - - + + engine::RenderEngine & Assembler::build () { + UNIMPLEMENTED ("the builder..."); } - - - + + + }}} // namespace proc::mobject::builder diff --git a/src/proc/mobject/builder/assembler.hpp b/src/proc/mobject/builder/assembler.hpp index 095052581..404df7560 100644 --- a/src/proc/mobject/builder/assembler.hpp +++ b/src/proc/mobject/builder/assembler.hpp @@ -21,6 +21,11 @@ */ +/** @file assembler.hpp + ** @todo initially generated code of unclear relevance + */ + + #ifndef MOBJECT_BUILDER_ASSEMBLER_H #define MOBJECT_BUILDER_ASSEMBLER_H @@ -40,7 +45,8 @@ namespace builder { class Assembler { public: - engine::RenderEngine & build () ; + engine::RenderEngine& + build (); // TODO: allocation, GC??? }; diff --git a/src/proc/mobject/builder/common.hpp b/src/proc/mobject/builder/common.hpp index 35d51c2a5..ff303344b 100644 --- a/src/proc/mobject/builder/common.hpp +++ b/src/proc/mobject/builder/common.hpp @@ -21,6 +21,12 @@ */ +/** @file common.hpp + ** @todo initially generated code of unclear relevance + ** @deprecated 2016 is a common inclusion file really such a good idea? + */ + + #ifndef MOBJECT_BUILDER_COMMON_H #define MOBJECT_BUILDER_COMMON_H diff --git a/src/proc/mobject/builder/conmanager.cpp b/src/proc/mobject/builder/conmanager.cpp index 082512d90..01941e5b3 100644 --- a/src/proc/mobject/builder/conmanager.cpp +++ b/src/proc/mobject/builder/conmanager.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file conmanager.cpp + ** @todo initially generated code of unclear relevance + */ + + +#include "lib/error.hpp" #include "proc/mobject/builder/conmanager.hpp" #include "proc/control/stypemanager.hpp" @@ -31,13 +37,13 @@ namespace builder { /** - * TODO !!!!!!!!!!!!!!!!!! + * @todo TODO IT!!!!!!!!!!!!!!!!!! */ int ConManager::getConnection () { + UNIMPLEMENTED ("wiring in the builder..."); } - - - + + }}} // namespace proc::mobject::builder diff --git a/src/proc/mobject/builder/conmanager.hpp b/src/proc/mobject/builder/conmanager.hpp index 6e9c850c0..454dbd6ff 100644 --- a/src/proc/mobject/builder/conmanager.hpp +++ b/src/proc/mobject/builder/conmanager.hpp @@ -21,6 +21,11 @@ */ +/** @file conmanager.hpp + ** @todo initially generated code of unclear relevance + */ + + #ifndef PROC_MOBJECT_BUILDER_CONMANAGER_H #define PROC_MOBJECT_BUILDER_CONMANAGER_H @@ -38,7 +43,7 @@ namespace builder { * with the corresponding ParamProviders (automation) in the Session. * Questions regarding the possibility of a media stream connection are * delegated internally to the STypeManager. - * \par + * * The primary service of the connection manager is to accept a wiring request * and handle the details of establishing the necessary connections. */ @@ -46,9 +51,9 @@ namespace builder { { public: /** - * TODO just a design sketch, work out signatures etc... + * @todo just a design sketch from 2008, work out signatures etc... */ - int getConnection () ; + int getConnection (); }; diff --git a/src/proc/mobject/builder/mould.hpp b/src/proc/mobject/builder/mould.hpp index e1bf5cb73..371482d3b 100644 --- a/src/proc/mobject/builder/mould.hpp +++ b/src/proc/mobject/builder/mould.hpp @@ -21,6 +21,17 @@ */ +/** @file mould.hpp + ** Builder tool kit. + ** On the basic level, the builder works by wiring up new processing nodes, + ** guided by a small number of preconfigured building patterns. For each such + ** basic wiring situation, there is a builder::Mould, which acts as a fixed + ** counterpart for the node network in construction to hinge on. + ** + ** @todo plan and draft from 2008 -- still considered relevant as of 2016 + */ + + #ifndef MOBJECT_BUILDER_MOULD_H #define MOBJECT_BUILDER_MOULD_H @@ -40,21 +51,21 @@ namespace builder { /** - * Interface: a workbench-like tool used by the builder + * Interface: a workbench-like tool used by the builder * for wiring up a specific building situation, followed by - * the application/execution of a single building step. Mould is + * the application/execution of a single building step. Mould is * conceived as the passive part, while usually the ProcPatt plays * the role of the active counterpart. By means of the Mould interface, * the specifics of a build situation are abstracted away, thus allowing * the processing pattern to be defined as working on symbolic locations. * Most commonly this is "current", denoting the render node just being built. - *
  • PipeMould supports attaching an effect to a pipe
    • - *
  • combining pipes via a transition is done by a CombiningMould
    • - *
  • a SourceChainMould allows to start out from a source reader and build a clip
    • - *
  • wiring general connections is supported by the WiringMould
    • - *
+ * - PipeMould supports attaching an effect to a pipe + * - combining pipes via a transition is done by a CombiningMould + * - a SourceChainMould allows to start out from a source reader and build a clip + * - wiring general connections is supported by the WiringMould + * * @see ToolFactory - * @see NodeCreatorTool + * @see NodeCreatorTool */ class Mould { diff --git a/src/proc/mobject/builder/nodecreatortool.cpp b/src/proc/mobject/builder/nodecreatortool.cpp index 7f617f28e..fcec1ac82 100644 --- a/src/proc/mobject/builder/nodecreatortool.cpp +++ b/src/proc/mobject/builder/nodecreatortool.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file nodecreatortool.cpp + ** Implementation of visitor logic to actually build the render node network + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + +#include "lib/error.hpp" #include "proc/mobject/builder/nodecreatortool.hpp" @@ -43,24 +50,28 @@ namespace builder { void NodeCreatorTool::treat (Buildable& something) { + UNIMPLEMENTED ("the builder tool..."); } void NodeCreatorTool::treat (Clip& clip) { + UNIMPLEMENTED ("the builder tool..."); } void NodeCreatorTool::treat (Effect& effect) { + UNIMPLEMENTED ("the builder tool..."); } void NodeCreatorTool::treat (Auto& automation) { + UNIMPLEMENTED ("the builder tool..."); } diff --git a/src/proc/mobject/builder/nodecreatortool.hpp b/src/proc/mobject/builder/nodecreatortool.hpp index c808dce2e..a6c79045b 100644 --- a/src/proc/mobject/builder/nodecreatortool.hpp +++ b/src/proc/mobject/builder/nodecreatortool.hpp @@ -21,6 +21,12 @@ */ +/** @file nodecreatortool.hpp + ** Visitor tool to work on the concrete model objects when building the render node network. + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #ifndef MOBJECT_BUILDER_NODECREATORTOOL_H #define MOBJECT_BUILDER_NODECREATORTOOL_H @@ -73,4 +79,4 @@ namespace builder { }}} // namespace proc:mobject::builder -#endif +#endif /*MOBJECT_BUILDER_NODECREATORTOOL_H*/ diff --git a/src/proc/mobject/builder/operationpoint.cpp b/src/proc/mobject/builder/operationpoint.cpp index db1165ff1..b3ef74831 100644 --- a/src/proc/mobject/builder/operationpoint.cpp +++ b/src/proc/mobject/builder/operationpoint.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file operationpoint.cpp + ** Implementation of primitive builder operations on at the _current point of operation_. + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #include "proc/mobject/builder/operationpoint.hpp" #include "proc/engine/procnode.hpp" #include "proc/asset/media.hpp" diff --git a/src/proc/mobject/builder/operationpoint.hpp b/src/proc/mobject/builder/operationpoint.hpp index e92505bb7..7f08b1218 100644 --- a/src/proc/mobject/builder/operationpoint.hpp +++ b/src/proc/mobject/builder/operationpoint.hpp @@ -21,6 +21,18 @@ */ +/** @file operationpoint.hpp + ** Abstraction to represent the current point of operation within the builder. + ** The Builder walks the tree of the high-level-model (session model) to generate + ** a (low-level) render node network. The current point of operation within this tree walk + ** is abstracted, to allow the use of some _building primitives._ A meta description of + ** *processing patterns* can be used then to control the actual build process, without + ** the need of hard wiring the individual builder steps. + ** + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #ifndef MOBJECT_BUILDER_OPERATIONPOINT_H #define MOBJECT_BUILDER_OPERATIONPOINT_H @@ -80,4 +92,4 @@ namespace builder { }}} // namespace proc::mobject::builder -#endif +#endif /*MOBJECT_BUILDER_OPERATIONPOINT_H*/ diff --git a/src/proc/mobject/builder/renderstate.hpp b/src/proc/mobject/builder/renderstate.hpp index 935aaab7e..10e9b68c1 100644 --- a/src/proc/mobject/builder/renderstate.hpp +++ b/src/proc/mobject/builder/renderstate.hpp @@ -21,6 +21,15 @@ */ +/** @file renderstate.hpp + ** Build and prepare the render state abstraction. + ** The intention was to rely later, during the actual rendering, on the + ** setup prepared here + ** @deprecated stalled design draft from 2008 -- especially the part regarding RenderSate + ** will likely be implemented in a different way + */ + + #ifndef MOBJECT_BUILDER_RENDERSTATE_H #define MOBJECT_BUILDER_RENDERSTATE_H @@ -37,7 +46,7 @@ namespace builder { /** * Encapsulates the logic used to get a "render process". - * The provided StateProxy serves to hold any mutalbe state used + * The provided StateProxy serves to hold any mutable state used * in the render process, so the rest of the render engine * can be stateless. * @todo probably the state management will work different (6/08) @@ -51,4 +60,4 @@ namespace builder { }}} // namespace proc::mobject::session -#endif +#endif /*MOBJECT_BUILDER_RENDERSTATE_H*/ diff --git a/src/proc/mobject/builder/segmentation-tool.cpp b/src/proc/mobject/builder/segmentation-tool.cpp index 895a2fe53..be65f0627 100644 --- a/src/proc/mobject/builder/segmentation-tool.cpp +++ b/src/proc/mobject/builder/segmentation-tool.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file segmentation-tool.cpp + ** Implementation of builder primitives to create a timeline segmentation. + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #include "proc/mobject/builder/segmentation-tool.hpp" diff --git a/src/proc/mobject/builder/segmentation-tool.hpp b/src/proc/mobject/builder/segmentation-tool.hpp index 720938cc5..d281f0c54 100644 --- a/src/proc/mobject/builder/segmentation-tool.hpp +++ b/src/proc/mobject/builder/segmentation-tool.hpp @@ -21,6 +21,16 @@ */ +/** @file segmentation-tool.hpp + ** Visiting tool to create a viable _segmentation_ of the timeline for rendering. + ** Within each such segment, the _configuration and wiring_ of the render node network + ** is considered stable. Any further variation within a segment is created solely by varying + ** parameters (automation). The created Segmentation is considered the "backbone" of the + ** low-level render node network + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #ifndef MOBJECT_BUILDER_SEGMENTATION_TOOL_H #define MOBJECT_BUILDER_SEGMENTATION_TOOL_H @@ -76,4 +86,4 @@ namespace builder { }}} // namespace proc::mobject::builder -#endif +#endif /*MOBJECT_BUILDER_SEGMENTATION_TOOL_H*/ diff --git a/src/proc/mobject/builder/toolfactory.cpp b/src/proc/mobject/builder/toolfactory.cpp index 9245f7d3a..39d5a0ed3 100644 --- a/src/proc/mobject/builder/toolfactory.cpp +++ b/src/proc/mobject/builder/toolfactory.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file toolfactory.cpp + ** Implementation of factory functions for the tools used within the Builder + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #include "proc/mobject/builder/toolfactory.hpp" #include "lib/util.hpp" diff --git a/src/proc/mobject/builder/toolfactory.hpp b/src/proc/mobject/builder/toolfactory.hpp index 80fc001fe..c0a0eb57b 100644 --- a/src/proc/mobject/builder/toolfactory.hpp +++ b/src/proc/mobject/builder/toolfactory.hpp @@ -21,6 +21,15 @@ */ +/** @file toolfactory.hpp + ** Factory to create the tools for the build process. + ** Obviously the logic to control and direct the build process will be attached + ** behind this interface. + ** + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #ifndef MOBJECT_BUILDER_TOOLFACTORY_H #define MOBJECT_BUILDER_TOOLFACTORY_H diff --git a/src/proc/mobject/builder/wiringrequest.hpp b/src/proc/mobject/builder/wiringrequest.hpp index 25f908994..a565a157f 100644 --- a/src/proc/mobject/builder/wiringrequest.hpp +++ b/src/proc/mobject/builder/wiringrequest.hpp @@ -21,6 +21,16 @@ */ +/** @file wiringrequest.hpp + ** Symbolic representation of a goal for node wiring. + ** A WiringRequest is discovered while walking the Session model, and will be resolved + ** later, when the target for the desired connection is available. When all wiring requests + ** are resolved, the build process finishes. Thus, creating and resolving of such requests + ** is the "fuel" actually to drive the Builder. + ** @todo stalled design draft from 2008 -- basically still considered relevant as of 2016 + */ + + #ifndef MOBJECT_BUILDER_WIRINGREQUEST_H #define MOBJECT_BUILDER_WIRINGREQUEST_H diff --git a/src/proc/mobject/builderfacade.cpp b/src/proc/mobject/builderfacade.cpp index ec4c86682..3d670f1da 100644 --- a/src/proc/mobject/builderfacade.cpp +++ b/src/proc/mobject/builderfacade.cpp @@ -21,26 +21,34 @@ * *****************************************************/ +/** @file builderfacade.cpp + ** Implementation of top-level access to builder functionality + */ + + #include "proc/mobject/builder/common.hpp" #include "proc/mobject/builderfacade.hpp" +#include "proc/mobject/session/fixture.hpp" namespace proc { namespace mobject { - - /** - * Main Operation of the Builder: - * create a render engine for a given part of the timeline - */ - engine::RenderEngine & - BuilderFacade::buildEngine () - { - //////////////////////TODO - } + using session::Fixture; LUMIERA_ERROR_DEFINE (BUILDER_LIFECYCLE, "Builder activated while in non operational state"); + /** + * Main Operation of the Builder: + * rebuild the low-level model based on the current contents of the Session. + */ + Fixture& + BuilderFacade:: rebuildFixture () + { + UNIMPLEMENTED ("build the builder..."); + } + + }} // namespace mobject diff --git a/src/proc/mobject/builderfacade.hpp b/src/proc/mobject/builderfacade.hpp index c58ce3692..2148e651b 100644 --- a/src/proc/mobject/builderfacade.hpp +++ b/src/proc/mobject/builderfacade.hpp @@ -21,15 +21,29 @@ */ -#ifndef MOBJECT_BUILDERFACADE_H -#define MOBJECT_BUILDERFACADE_H +/** @file builderfacade.hpp + ** Proc-Layer Facade: access to the Builder. + ** The Builder walks the Session model to compile a corresponding render node network. + ** + ** @todo as of 2016 the builder, as the most crucial component within the architecture, + ** still remains to be addressed. While we'd hoped to get ahead faster, it is considered + ** a good idea not to decide upon the implementation based on assumptions. + ** We will start building the builder "when it is ready" + */ + +#ifndef PROC_MOBJECT_BUILDERFACADE_H +#define PROC_MOBJECT_BUILDERFACADE_H + +#include "lib/error.hpp" #include "proc/mobject/builder/common.hpp" -#include "proc/engine/renderengine.hpp" namespace proc { namespace mobject { + namespace session { + class Fixture; + } LUMIERA_ERROR_DECLARE (BUILDER_LIFECYCLE); ///< Builder activated while in non operational state @@ -42,17 +56,10 @@ namespace mobject { class BuilderFacade { public: - /** - * Main Operation of the Builder: - * create a render engine for a given part of the timeline - * @deprecated thats a placeholder! the real invocation is now - * in the course of being worked out ////////////TODO 12/2010 - */ - engine::RenderEngine & buildEngine () ; - // TODO: allocation, GC?????? + session::Fixture & rebuildFixture (); }; }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_BUILDERFACADE_H*/ diff --git a/src/proc/mobject/explicitplacement.hpp b/src/proc/mobject/explicitplacement.hpp index 558be04f6..655a4c6a1 100644 --- a/src/proc/mobject/explicitplacement.hpp +++ b/src/proc/mobject/explicitplacement.hpp @@ -21,8 +21,23 @@ */ -#ifndef MOBJECT_EXPLICITPLACEMENT_H -#define MOBJECT_EXPLICITPLACEMENT_H +/** @file explicitplacement.hpp + ** Core abstraction: completely resolved placement of an MObject + ** Within the session model, all media objects are attached with the help + ** of mobject::Placement elements. These are the "glue" to stitch the model + ** together. However, placements are typically only defined in parts, and what + ** is left out in the definition is assumed to be _"obvious from the context"._ + ** + ** The core operation within Proc-Layer is the Builder run, which walks the Session model + ** to resolve and fill in all the contextual information. The result is a completely resolved + ** Placement for each actually visible and relevant entity. Such is represented as ExplicitPlacement. + ** These are arranged into the backbone structure, the Fixture, and the actual render node network + ** necessary to _render_ those contents is attached below. + */ + + +#ifndef PROC_MOBJECT_EXPLICITPLACEMENT_H +#define PROC_MOBJECT_EXPLICITPLACEMENT_H #include "proc/mobject/placement.hpp" @@ -85,4 +100,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_EXPLICITPLACEMENT_H*/ diff --git a/src/proc/mobject/interpolator.cpp b/src/proc/mobject/interpolator.cpp deleted file mode 100644 index ca061f37e..000000000 --- a/src/proc/mobject/interpolator.cpp +++ /dev/null @@ -1,33 +0,0 @@ -/* - Interpolator - denotes a facility to get (continuously interpolated) parameter values - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/mobject/interpolator.hpp" - -namespace proc { -namespace mobject { - - /** */ - - - -}} // namespace proc::mobject diff --git a/src/proc/mobject/interpolator.hpp b/src/proc/mobject/interpolator.hpp index ec70070f5..9d59ed8b4 100644 --- a/src/proc/mobject/interpolator.hpp +++ b/src/proc/mobject/interpolator.hpp @@ -21,8 +21,15 @@ */ -#ifndef MOBJECT_INTERPOLATOR_H -#define MOBJECT_INTERPOLATOR_H +/** @file interpolator.hpp + ** Core abstraction: automation parameter interpolator + ** Each interpolator implementation has the ability to resolve intermediary + ** values and to provide a parameter value for _every arbitrary point in time._ + */ + + +#ifndef PROC_MOBJECT_INTERPOLATOR_H +#define PROC_MOBJECT_INTERPOLATOR_H @@ -31,7 +38,7 @@ namespace mobject { /** - * Provides the implementation for getting the acutal value + * Provides the implementation for getting the actual value * of a time varying or automated effect/plugin parameter */ template @@ -43,4 +50,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_INTERPOLATOR_H*/ diff --git a/src/proc/mobject/mobject.cpp b/src/proc/mobject/mobject.cpp index 48c187141..e4f1047d7 100644 --- a/src/proc/mobject/mobject.cpp +++ b/src/proc/mobject/mobject.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file mobject.cpp + ** Top level implementation functions globally relevant to the session model + */ + + #include "proc/mobject/mobject.hpp" #include "proc/mobject/session/mobjectfactory.hpp" #include "lib/time/timevalue.hpp" diff --git a/src/proc/mobject/mobject.hpp b/src/proc/mobject/mobject.hpp index cf0ce6217..214ec19ff 100644 --- a/src/proc/mobject/mobject.hpp +++ b/src/proc/mobject/mobject.hpp @@ -21,8 +21,23 @@ */ -#ifndef MOBJECT_MOBJECT_H -#define MOBJECT_MOBJECT_H +/** @file mobject.hpp + ** Core abstraction of the Session model: a media object. + ** The contents of the edit and thus of the session are modelled as a collection + ** of MObject entities, each attached by a Placement. Together these form what can + ** be conceived as an _instance_ of the object. The Placement constitutes the relative + ** and contextual information, while the MObject provides the identity and the link + ** to actual media content or plug-in implementations. + ** + ** @todo as of 2016, this core part of the model still needs to be actually implemented. + ** Most of the code in this hierarchy is preliminary or placeholder code, since we + ** prefer to build the system from ground up, not top-down. It is very likely, that + ** MObject will be just a data tuple in the end. + */ + + +#ifndef PROC_MOBJECT_MOBJECT_H +#define PROC_MOBJECT_MOBJECT_H #include "proc/common.hpp" #include "proc/mobject/builder/buildertool.hpp" @@ -108,4 +123,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_MOBJECT_H*/ diff --git a/src/proc/mobject/output-designation.hpp b/src/proc/mobject/output-designation.hpp index c06cc34b4..c9469bdf8 100644 --- a/src/proc/mobject/output-designation.hpp +++ b/src/proc/mobject/output-designation.hpp @@ -21,6 +21,22 @@ */ +/** @file output-designation.hpp + ** Core abstraction: symbolic representation of some output target. + ** An OutputDesignation represents something you might want to connect to + ** or towards which you'd like to direct output. It might be _absolute,_ in + ** which case it represents an actual output device attached to the system, + ** or it might be relative, as a placeholder for further wiring and output routing. + ** An example for the latter would be the "master bus". + ** + ** The concept of an OutputDesignation plays a crucial role to allow flexible connection + ** and rearrangement of media content. It allows to build partial structures, which can + ** be connected automatically to a suitable output when placed into the appropriate context. + ** In the end, the Builder will resolve all output designations, finally leading to a fixed + ** set of exit nodes, which can be pulled to deliver content. + */ + + #ifndef PROC_MOBJECT_OUTPUT_DESIGNATION_H #define PROC_MOBJECT_OUTPUT_DESIGNATION_H @@ -49,7 +65,7 @@ namespace mobject { * OutputDesignation is always an internal and relative specification * and boils down to referring an asset::Pipe by ID. In order to become * actually effective, some object within the model additionally - * needs to \em claim this pipe-ID, meaning that this object + * needs to _claim_ this pipe-ID, meaning that this object * states to root and represent this pipe. When the builder * encounters a pair of (OutputDesignation, OutputClaim), * an actual stream connection will be wired in the @@ -118,4 +134,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_OUTPUT_DESIGNATION_H*/ diff --git a/src/proc/mobject/parameter.cpp b/src/proc/mobject/parameter.cpp index 5a00644ce..25cd61034 100644 --- a/src/proc/mobject/parameter.cpp +++ b/src/proc/mobject/parameter.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file parameter.cpp + ** Implementation functions of the Parameter abstraction. + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. + */ + + #include "lib/error.hpp" #include "proc/mobject/parameter.hpp" #include "proc/mobject/paramprovider.hpp" diff --git a/src/proc/mobject/parameter.hpp b/src/proc/mobject/parameter.hpp index fa256d0f6..0782557f0 100644 --- a/src/proc/mobject/parameter.hpp +++ b/src/proc/mobject/parameter.hpp @@ -21,8 +21,15 @@ */ -#ifndef PROC_MOBJECT_PARAMETER_H -#define PROC_MOBJECT_PARAMETER_H +/** @file parameter.hpp + ** Core abstraction: parameter to be controlled and possibly automated. + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. + */ + + +#ifndef PROC_PROC_MOBJECT_PARAMETER_H +#define PROC_PROC_MOBJECT_PARAMETER_H @@ -52,4 +59,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_PROC_MOBJECT_PARAMETER_H*/ diff --git a/src/proc/mobject/paramprovider.cpp b/src/proc/mobject/paramprovider.cpp index 9bdeeb452..617ac4618 100644 --- a/src/proc/mobject/paramprovider.cpp +++ b/src/proc/mobject/paramprovider.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file paramprovider.cpp + ** Implementation functions of the Parameter abstraction. + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. + */ + + #include "proc/mobject/paramprovider.hpp" #include "proc/mobject/parameter.hpp" #include "proc/mobject/interpolator.hpp" diff --git a/src/proc/mobject/paramprovider.hpp b/src/proc/mobject/paramprovider.hpp index 3be0b2206..24bdb8ec7 100644 --- a/src/proc/mobject/paramprovider.hpp +++ b/src/proc/mobject/paramprovider.hpp @@ -21,8 +21,15 @@ */ -#ifndef MOBJECT_PARAMPROVIDER_H -#define MOBJECT_PARAMPROVIDER_H +/** @file paramprovider.hpp + ** Core abstraction: an entity to expose a single parameter + ** + ** @todo as of 2016, we still need to work out our parameter/automation concept. + */ + + +#ifndef PROC_MOBJECT_PARAMPROVIDER_H +#define PROC_MOBJECT_PARAMPROVIDER_H @@ -52,4 +59,4 @@ namespace mobject { }} // namespace proc::mobject -#endif +#endif /*PROC_MOBJECT_PARAMPROVIDER_H*/ diff --git a/src/proc/mobject/placement.cpp b/src/proc/mobject/placement.cpp index 4f97a3a1a..200811d36 100644 --- a/src/proc/mobject/placement.cpp +++ b/src/proc/mobject/placement.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file placement.cpp + ** Implementation functions belonging to the Placement entity + */ + + #include "proc/mobject/placement.hpp" #include "proc/mobject/explicitplacement.hpp" #include "proc/mobject/mobject.hpp" diff --git a/src/proc/mobject/placement.hpp b/src/proc/mobject/placement.hpp index 25812e85c..1f77ad14b 100644 --- a/src/proc/mobject/placement.hpp +++ b/src/proc/mobject/placement.hpp @@ -21,19 +21,22 @@ */ -/** @file placement.hpp - ** Placements are at the very core of all editing operations, - ** because they act as handles to access the media objects to be manipulated. - ** Moreover, Placements are the actual "content" of the Session and Fixture and thus - ** are small handle like objects. Many editing tasks include locating some Placement - ** within the Session or directly take a ref to a Placement. +/** @file placement.hpp + ** Core abstraction: placement of a media object into session context. + ** Placements are at the very core of all editing operations, because they act + ** as handles to access the media objects to be manipulated. + ** Moreover, Placements are the actual "content" stored within the the Session and Fixture + ** data structure and thus are small handle like objects, which can be processed efficiently. + ** Many editing tasks include locating some Placement within the Session or directly take + ** a reference to a Placement. A Placement represents a _specific way to attach content._ + ** They may refer to contextual information and relate themselves to other placements. ** - ** Placements are refcounting smart pointers: By acting on the Placement object, - ** we can change parameters of the way the media object is placed (e.g. adjust an offset), - ** while by dereferencing the Placement object, we access the "real" media object. - ** Usually, any MObject is created by a factory and immediately wrapped into a Placement, + ** On the implementation level, placements are *refcounting smart pointers*: By acting + ** on the Placement object, we can change parameters of the way the media object is placed + ** (e.g. adjust an offset), while by dereferencing the Placement object, we access the media + ** object itself. Usually, any MObject is created by a factory and immediately wrapped into a Placement, ** which takes ownership of the MObject. - ** + ** ** Besides being a handle, Placements define the logical position where some MObject is ** supposed to be located within the Session or Fixture. The way in which this placing happens ** is controlled and parametrised by a collection (chain) of LocatingPin objects. By adding @@ -42,21 +45,21 @@ ** absolute position (time, output). ** ** Together, this yields semantics somewhere in between value semantics and reference semantics. - ** As any smart-ptr, placements are copyable, but each such copy takes on a distinct identity. - ** Moreover, when added to the Session, a placement acts as if it was an \em instance of the object + ** As any smart-ptr, placements are copyable, but each such copy takes on a _distinct identity._ + ** Moreover, when added to the Session, a placement acts as if it was an _instance_ of the object ** it points at, with the purpose to bind this instance into the Session with specific placement - ** properties. Thus, such a placement-within-session \em is an distinguishable entity, because - ** the settings on the contained LocatingPin chain \em do constitute the relation properties + ** properties. Thus, such a placement-within-session _is_ a distinguishable entity, because + ** the settings on the contained LocatingPin chain _do constitute_ the relation properties ** of the MObject "placed" by this placement. To support this rather ref-like semantics, any - ** placement has an embedded ID (identity). Building on this ID, it is possible to create a - ** smart-ptr like PlacementRef to denote a specific placement found within the Session. + ** placement has an embedded ID (identity). Building on this ID, it is possible in turn to + ** create a smart-ptr like PlacementRef to denote a specific placement found within the Session. ** ** Placements are templated on the type of the actual MObject they refer to, so, sometimes ** e.g. we rather use a Placement to be able to use the more specific methods of the - ** session::Clip interface. But please note the following detail: this type - ** labelling and downcasting is the only difference between these subclasses, - ** besides that, they can be replaced literally by one another (slicing is accepted). - ** + ** session::Clip interface. But _please note the following detail:_ this type labelling + ** and downcasting is the _only_ difference between these subclasses, besides that, + ** they can be replaced literally by one another (slicing acceptable). + ** ** @see ExplicitPlacement ** @see LocatingPin interface for controlling the positioning parameters ** diff --git a/src/proc/mobject/session/abstractmo.cpp b/src/proc/mobject/session/abstractmo.cpp index aaba3176d..aeb4af956 100644 --- a/src/proc/mobject/session/abstractmo.cpp +++ b/src/proc/mobject/session/abstractmo.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file abstractmo.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/abstractmo.hpp" #include "lib/format-string.hpp" #include "lib/util.hpp" diff --git a/src/proc/mobject/session/abstractmo.hpp b/src/proc/mobject/session/abstractmo.hpp index 7c6b9ef70..093cfaeef 100644 --- a/src/proc/mobject/session/abstractmo.hpp +++ b/src/proc/mobject/session/abstractmo.hpp @@ -21,6 +21,11 @@ */ +/** @file abstractmo.hpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #ifndef MOBJECT_SESSION_ABSTRACTMO_H #define MOBJECT_SESSION_ABSTRACTMO_H diff --git a/src/proc/mobject/session/allocation.cpp b/src/proc/mobject/session/allocation.cpp index 5a8b50e61..3e8912eb7 100644 --- a/src/proc/mobject/session/allocation.cpp +++ b/src/proc/mobject/session/allocation.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file allocation.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/allocation.hpp" namespace proc { diff --git a/src/proc/mobject/session/allocation.hpp b/src/proc/mobject/session/allocation.hpp index 5f263310d..6f6881422 100644 --- a/src/proc/mobject/session/allocation.hpp +++ b/src/proc/mobject/session/allocation.hpp @@ -21,6 +21,12 @@ */ +/** @file allocation.hpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + ** @deprecated WTF? looks like a leftover of some early brainstorming... + */ + + #ifndef PROC_MOBJECT_SESSION_ALLOCATION_H #define PROC_MOBJECT_SESSION_ALLOCATION_H diff --git a/src/proc/mobject/session/auto.cpp b/src/proc/mobject/session/auto.cpp index 54032b633..e3e0ede12 100644 --- a/src/proc/mobject/session/auto.cpp +++ b/src/proc/mobject/session/auto.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file auto.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/auto.hpp" namespace proc { diff --git a/src/proc/mobject/session/auto.hpp b/src/proc/mobject/session/auto.hpp index 152baa851..69136380b 100644 --- a/src/proc/mobject/session/auto.hpp +++ b/src/proc/mobject/session/auto.hpp @@ -21,6 +21,11 @@ */ +/** @file auto.hpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #ifndef PROC_MOBJECT_SESSION_AUTO_H #define PROC_MOBJECT_SESSION_AUTO_H diff --git a/src/proc/mobject/session/binding.cpp b/src/proc/mobject/session/binding.cpp index acc6dee79..7c85195e3 100644 --- a/src/proc/mobject/session/binding.cpp +++ b/src/proc/mobject/session/binding.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file 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 + */ + + #include "proc/mobject/session/binding.hpp" #include "proc/asset/sequence.hpp" diff --git a/src/proc/mobject/session/binding.hpp b/src/proc/mobject/session/binding.hpp index 089b946b1..1d9d638dc 100644 --- a/src/proc/mobject/session/binding.hpp +++ b/src/proc/mobject/session/binding.hpp @@ -21,6 +21,13 @@ */ +/** @file binding.hpp + ** MObject in session to represent the top-level binding of a sequence + ** @todo stalled effort towards a session implementation from 2010 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #ifndef PROC_MOBJECT_SESSION_BINDING_H #define PROC_MOBJECT_SESSION_BINDING_H diff --git a/src/proc/mobject/session/bus-mo.cpp b/src/proc/mobject/session/bus-mo.cpp index ac06ee6c0..1f8faf21e 100644 --- a/src/proc/mobject/session/bus-mo.cpp +++ b/src/proc/mobject/session/bus-mo.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file bus-mo.cpp + ** Implementation details for a _processing pipe_ representation in the Session model + ** @todo stalled effort towards a session implementation from 2010 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #include "proc/mobject/session/bus-mo.hpp" namespace proc { diff --git a/src/proc/mobject/session/bus-mo.hpp b/src/proc/mobject/session/bus-mo.hpp index 76ea650c4..24f591539 100644 --- a/src/proc/mobject/session/bus-mo.hpp +++ b/src/proc/mobject/session/bus-mo.hpp @@ -21,6 +21,16 @@ */ +/** @file bus-mo.hpp + ** MObject in the Session to represent a processing pipe. + ** Within the Session model, Pipes are conceptual entities, which do not correspond + ** 1:1 to some render nodes, but rather help the _user_ to organise the processing steps + ** required to get some piece of the film into desired shape + ** @todo stalled effort towards a session implementation from 2010 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #ifndef PROC_MOBJECT_SESSION_BUS_MO_H #define PROC_MOBJECT_SESSION_BUS_MO_H diff --git a/src/proc/mobject/session/clip.cpp b/src/proc/mobject/session/clip.cpp index 1461be405..1016b6df1 100644 --- a/src/proc/mobject/session/clip.cpp +++ b/src/proc/mobject/session/clip.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file 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 + */ + + #include "proc/mobject/session/clip.hpp" #include "proc/assetmanager.hpp" #include "proc/asset/media.hpp" @@ -38,18 +45,18 @@ namespace session { /** new clip-MO linked with the given asset::Clip. * Initially, this clip will cover the whole source media length. */ - Clip::Clip (const asset::Clip& clipDef, const Media& mediaDef) + Clip::Clip (asset::Clip const& clipDef, Media const& mediaDef) : mediaDef_(mediaDef) , clipDef_(clipDef) - { - setupLength(); - throwIfInvalid(); - } + { + setupLength(); + throwIfInvalid(); + } /** implementing the common MObject self test. - * Length definition is consitent, underlying + * Length definition is consistent, underlying * media def is accessible etc. */ bool Clip::isValid () const diff --git a/src/proc/mobject/session/clip.hpp b/src/proc/mobject/session/clip.hpp index c01e37e1f..bd38df1fa 100644 --- a/src/proc/mobject/session/clip.hpp +++ b/src/proc/mobject/session/clip.hpp @@ -21,6 +21,13 @@ */ +/** @file 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 + */ + + #ifndef PROC_MOBJECT_SESSION_CLIP_H #define PROC_MOBJECT_SESSION_CLIP_H diff --git a/src/proc/mobject/session/constraint.cpp b/src/proc/mobject/session/constraint.cpp index 1bedefbe1..48cc7d6e4 100644 --- a/src/proc/mobject/session/constraint.cpp +++ b/src/proc/mobject/session/constraint.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file constraint.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/constraint.hpp" namespace proc { diff --git a/src/proc/mobject/session/constraint.hpp b/src/proc/mobject/session/constraint.hpp index 827a48fc1..766382064 100644 --- a/src/proc/mobject/session/constraint.hpp +++ b/src/proc/mobject/session/constraint.hpp @@ -21,6 +21,12 @@ */ +/** @file constraint.hpp + ** Specialised LocatingPin for use in placements + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #ifndef PROC_MOBJECT_SESSION_CONSTRAINT_H #define PROC_MOBJECT_SESSION_CONSTRAINT_H diff --git a/src/proc/mobject/session/effect.cpp b/src/proc/mobject/session/effect.cpp index fe78b195b..f4bac6756 100644 --- a/src/proc/mobject/session/effect.cpp +++ b/src/proc/mobject/session/effect.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file effect.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/effect.hpp" namespace proc { @@ -33,7 +38,7 @@ namespace session { asset::Proc const& Effect::getProcAsset() const { - UNIMPLEMENTED ("how to access the processing asset assotiated to a given Effect-MObject"); + UNIMPLEMENTED ("how to access the processing asset associated to a given Effect-MObject"); } diff --git a/src/proc/mobject/session/effect.hpp b/src/proc/mobject/session/effect.hpp index c1a84b31b..b54ed80b6 100644 --- a/src/proc/mobject/session/effect.hpp +++ b/src/proc/mobject/session/effect.hpp @@ -21,6 +21,11 @@ */ +/** @file effect.hpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #ifndef PROC_MOBJECT_SESSION_EFFECT_H #define PROC_MOBJECT_SESSION_EFFECT_H diff --git a/src/proc/mobject/session/element-query.hpp b/src/proc/mobject/session/element-query.hpp index 486c737c9..132b06317 100644 --- a/src/proc/mobject/session/element-query.hpp +++ b/src/proc/mobject/session/element-query.hpp @@ -21,6 +21,14 @@ */ +/** @file element-query.hpp + ** Search and query services to discover contents of the session + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef PROC_MOBJECT_SESSION_ELEMENT_QUERY_H #define PROC_MOBJECT_SESSION_ELEMENT_QUERY_H diff --git a/src/proc/mobject/session/fixedlocation.cpp b/src/proc/mobject/session/fixedlocation.cpp index 59bd299b9..4cc323da2 100644 --- a/src/proc/mobject/session/fixedlocation.cpp +++ b/src/proc/mobject/session/fixedlocation.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file fixedlocation.cpp + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #include "proc/mobject/session/fixedlocation.hpp" namespace proc { diff --git a/src/proc/mobject/session/fixedlocation.hpp b/src/proc/mobject/session/fixedlocation.hpp index cab2b0698..7790a00b8 100644 --- a/src/proc/mobject/session/fixedlocation.hpp +++ b/src/proc/mobject/session/fixedlocation.hpp @@ -21,6 +21,17 @@ */ +/** @file fixedlocation.hpp + ** Specialised LocatingPin for use in Placement, especially for globally fixed positions + ** The FixedLocation is assumed to play a central role within the Build process, which + ** ultimately aims ad resolving any part of the session into either a wiring directive + ** or a piece of media or processing to happen at a location fixed in time. + ** + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #ifndef PROC_MOBJECT_SESSION_FIXEDLOCATION_H #define PROC_MOBJECT_SESSION_FIXEDLOCATION_H diff --git a/src/proc/mobject/session/fixture.cpp b/src/proc/mobject/session/fixture.cpp index 3f4aac79e..70b705580 100644 --- a/src/proc/mobject/session/fixture.cpp +++ b/src/proc/mobject/session/fixture.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file fixture.cpp + ** Implementation of the Fixture datastructure + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/fixture.hpp" #include "include/logging.h" diff --git a/src/proc/mobject/session/fixture.hpp b/src/proc/mobject/session/fixture.hpp index 4aae36b47..8d92ecbd3 100644 --- a/src/proc/mobject/session/fixture.hpp +++ b/src/proc/mobject/session/fixture.hpp @@ -21,6 +21,25 @@ */ +/** @file fixture.hpp + ** Backbone data structure of the low-level render node model + ** The fixture defines the boundary between the Session (high-level) realm + ** and the internals of the render engine. The goal of a Builder run is to + ** build a new Fixture. All relative or indirect referrals are resolved at that point + ** and all time positions or output designations are made explicit. The Fixture defines + ** a Segmentation of every (top-level) timeline, and thus defines those segments which + ** can be rendered with a single wiring configuration. This Segmentation, as defined as + ** part of the Fixture, is also the foundation for memory management within the engine + ** model, since the allocation of render nodes for a given segment happens at once, and + ** segments are obliterated as a whole, when being replaced by a new version as result + ** of a more recent builder run. Ongoing render processes are also tracked per segment, + ** which allows the individual calculation steps just to assume the data is "there". + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef MOBJECT_SESSION_FIXTURE_H #define MOBJECT_SESSION_FIXTURE_H diff --git a/src/proc/mobject/session/fork.cpp b/src/proc/mobject/session/fork.cpp index c5e800b19..e6fd9b1ff 100644 --- a/src/proc/mobject/session/fork.cpp +++ b/src/proc/mobject/session/fork.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file fork.cpp + ** Implementation of the basic grouping device within the session ("Track" / "Media Bin") + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/fork.hpp" diff --git a/src/proc/mobject/session/fork.hpp b/src/proc/mobject/session/fork.hpp index da98b3258..fb25f2fa4 100644 --- a/src/proc/mobject/session/fork.hpp +++ b/src/proc/mobject/session/fork.hpp @@ -21,6 +21,36 @@ */ +/** @file fork.hpp + ** Organisational grouping device within the Session model ("Track" / "Media Bin"). + ** Within Lumiera, Tracks bear no direct relation to the rendering or calculation process; + ** rather they are just conceived as a space for the user to arrange the parts included + ** into the edit. + ** + ** A Fork is a nested tree-shaped structure. When integrated into a sequence, it will be + ** rendered in the familiar way, as tracks with media clips. But at the same time, when + ** accessed through the _Asset management view_ ("bookkeeping view"), a fork appears as + ** nested folder structure to hold media clips. + ** + ** Most importantly, a Fork defines a _system of nested scopes._ When discovering details + ** of the wiring, setup and configuration, the Build process will look into the enclosing + ** scope to fill in any part not defined locally at a given media object. Go give a typical + ** example, the _volume for sound playback_ can be defined in some root scope, causing all + ** sound objects to _inherit_ that volume setting -- unless shadowed by a more specialised + ** setting closer in scope to the sound object in question. This allows to set up global + ** properties and then to override them locally, for a group of objects located in some + ** sub-fork. + ** + ** @note to stress this point: in Lumiera we do _not conceive tracks as some kind of + ** channel, with media data flowing through the tracks._ Also, _tracks are not layers._ + ** This also means, there is _no distinction in audio and video tracks._ + ** We leave it at the user's discretion how she wants to organise the edit. + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef MOBJECT_SESSION_FORK_H #define MOBJECT_SESSION_FORK_H diff --git a/src/proc/mobject/session/generator-mo.cpp b/src/proc/mobject/session/generator-mo.cpp index a57ff41c9..f7f56449e 100644 --- a/src/proc/mobject/session/generator-mo.cpp +++ b/src/proc/mobject/session/generator-mo.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file generator-mo.cpp + ** @todo WIP implementation of player subsystem from 2011 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/generator-mo.hpp" //#include "proc/assetmanager.hpp" //#include "proc/asset/media.hpp" diff --git a/src/proc/mobject/session/generator-mo.hpp b/src/proc/mobject/session/generator-mo.hpp index 8df786d81..35bef01af 100644 --- a/src/proc/mobject/session/generator-mo.hpp +++ b/src/proc/mobject/session/generator-mo.hpp @@ -21,6 +21,14 @@ */ +/** @file generator-mo.hpp + ** A data generator media object. + ** Can be used as placeholder, or as testing device + ** @todo WIP implementation of player subsystem from 2011 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef PROC_MOBJECT_SESSION_GENERATOR_MO_H #define PROC_MOBJECT_SESSION_GENERATOR_MO_H diff --git a/src/proc/mobject/session/label.cpp b/src/proc/mobject/session/label.cpp index f14c1520b..c83b90d87 100644 --- a/src/proc/mobject/session/label.cpp +++ b/src/proc/mobject/session/label.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file label.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/label.hpp" #include "lib/util.hpp" diff --git a/src/proc/mobject/session/label.hpp b/src/proc/mobject/session/label.hpp index 74c7e0bae..ea6b5b3a4 100644 --- a/src/proc/mobject/session/label.hpp +++ b/src/proc/mobject/session/label.hpp @@ -21,6 +21,18 @@ */ +/** @file label.hpp + ** A marker or reference point in the Session. + ** Label MObjects can be [placed](\ref Placement) 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. + ** + ** @todo result of the very first code generation from UML in 2008. + ** @todo this is expected to become a very important facility eventually, so expec a lot of rework here... + */ + + #ifndef PROC_MOBJECT_SESSION_LABEL_H #define PROC_MOBJECT_SESSION_LABEL_H diff --git a/src/proc/mobject/session/locatingpin.cpp b/src/proc/mobject/session/locatingpin.cpp index 6f509e6b1..d1424dbe2 100644 --- a/src/proc/mobject/session/locatingpin.cpp +++ b/src/proc/mobject/session/locatingpin.cpp @@ -21,6 +21,15 @@ * *****************************************************/ +/** @file locatingpin.cpp + ** Implementation of the query resolving mechanics within a Placement. + ** All MObject entities within the session are attached via Placement, + ** and each such Placement holds a list of _constraints,_ represented as LocatingPin. + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #include "proc/mobject/mobject.hpp" #include "proc/mobject/placement.hpp" #include "proc/mobject/session/locatingpin.hpp" diff --git a/src/proc/mobject/session/meta.cpp b/src/proc/mobject/session/meta.cpp index 275e585aa..d0891b5f0 100644 --- a/src/proc/mobject/session/meta.cpp +++ b/src/proc/mobject/session/meta.cpp @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file meta.cpp + ** implementation details regarding the Meta asset abstraction + ** + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 not sure if we really need a separate translation unit for this? + */ + + #include "proc/mobject/session/meta.hpp" namespace proc { diff --git a/src/proc/mobject/session/meta.hpp b/src/proc/mobject/session/meta.hpp index db49c9ed5..0cff68e6f 100644 --- a/src/proc/mobject/session/meta.hpp +++ b/src/proc/mobject/session/meta.hpp @@ -21,6 +21,13 @@ */ +/** @file 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 + */ + + #ifndef PROC_MOBJECT_SESSION_META_H #define PROC_MOBJECT_SESSION_META_H diff --git a/src/proc/mobject/session/mobjectfactory.cpp b/src/proc/mobject/session/mobjectfactory.cpp index 2a03d3224..82e6bb764 100644 --- a/src/proc/mobject/session/mobjectfactory.cpp +++ b/src/proc/mobject/session/mobjectfactory.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file mobjectfactory.cpp + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #include "proc/mobject/session/mobjectfactory.hpp" #include "proc/mobject/session/root.hpp" #include "proc/mobject/session/clip.hpp" diff --git a/src/proc/mobject/session/mobjectfactory.hpp b/src/proc/mobject/session/mobjectfactory.hpp index 86a50b6f4..5edcefe3e 100644 --- a/src/proc/mobject/session/mobjectfactory.hpp +++ b/src/proc/mobject/session/mobjectfactory.hpp @@ -21,6 +21,14 @@ */ +/** @file mobjectfactory.hpp + ** Core factory to generate media objects for use in the Session model. + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework. + ** In fact I am quite unhappy with the shape of this code + */ + + #ifndef PROC_MOBJECT_SESSION_MOBJECTFACTORY_H #define PROC_MOBJECT_SESSION_MOBJECTFACTORY_H diff --git a/src/proc/mobject/session/placement-index-query-resolver.cpp b/src/proc/mobject/session/placement-index-query-resolver.cpp index 540f3677f..b8975c20c 100644 --- a/src/proc/mobject/session/placement-index-query-resolver.cpp +++ b/src/proc/mobject/session/placement-index-query-resolver.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file placement-index-query-resolver.cpp + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/placement-index-query-resolver.hpp" #include "proc/mobject/session/scope-query.hpp" #include "proc/mobject/placement.hpp" diff --git a/src/proc/mobject/session/plug.cpp b/src/proc/mobject/session/plug.cpp index 0e449c9fc..0b6520684 100644 --- a/src/proc/mobject/session/plug.cpp +++ b/src/proc/mobject/session/plug.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file plug.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/plug.hpp" #include "proc/asset/pipe.hpp" diff --git a/src/proc/mobject/session/plug.hpp b/src/proc/mobject/session/plug.hpp index 315a582c0..f7d5f574f 100644 --- a/src/proc/mobject/session/plug.hpp +++ b/src/proc/mobject/session/plug.hpp @@ -21,6 +21,11 @@ */ +/** @file plug.hpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #ifndef MOBJECT_SESSION_PLUG_H #define MOBJECT_SESSION_PLUG_H @@ -40,7 +45,7 @@ namespace session { class Plug : public Wish { protected: - /** the Pipe this MObject wants to be conected to */ + /** the Pipe this MObject wants to be connected to */ asset::Pipe* outPipe; ////////////////////////////////TODO: shared_ptr }; diff --git a/src/proc/mobject/session/query-focus-stack.hpp b/src/proc/mobject/session/query-focus-stack.hpp index e6c2e79c9..15d9e2625 100644 --- a/src/proc/mobject/session/query-focus-stack.hpp +++ b/src/proc/mobject/session/query-focus-stack.hpp @@ -21,6 +21,13 @@ */ +/** @file query-focus-stack.hpp + ** Implementation facility to work with and navigate nested scopes + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef MOBJECT_SESSION_QUERY_FOCUS_STACK_H #define MOBJECT_SESSION_QUERY_FOCUS_STACK_H @@ -47,7 +54,7 @@ namespace session { * a boost::intrusive_ptr, which stores the ref-count within * the mentioned ScopePath frames located in the stack. * - * \par automatic cleanup of unused frames + * ## automatic cleanup of unused frames * * The stack is aware of this ref-counting mechanism and will -- * on each access -- automatically clean up any unused frames starting @@ -194,4 +201,4 @@ namespace session { }}} // namespace mobject::session -#endif +#endif /*MOBJECT_SESSION_QUERY_FOCUS_STACK_H*/ diff --git a/src/proc/mobject/session/query-focus.cpp b/src/proc/mobject/session/query-focus.cpp index 9e16a2812..9d4baa51b 100644 --- a/src/proc/mobject/session/query-focus.cpp +++ b/src/proc/mobject/session/query-focus.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file query-focus.cpp + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/query-focus.hpp" #include "proc/mobject/mobject.hpp" #include "lib/format-string.hpp" diff --git a/src/proc/mobject/session/query-focus.hpp b/src/proc/mobject/session/query-focus.hpp index 8f68ca707..da1987bd0 100644 --- a/src/proc/mobject/session/query-focus.hpp +++ b/src/proc/mobject/session/query-focus.hpp @@ -21,6 +21,29 @@ */ +/** @file query-focus.hpp + ** Representation of the _current scope_ when navigating the session model. + ** Session contents may be discovered by query, and a _current location_ plays a crucial + ** role to fill in any missing details for resolving such a query. Thus, any code in need + ** to query contents or otherwise discover settings currently in effect within a given scope, + ** need to manage the position, where the query resolution is assumed to happen. The query focus + ** acts as an abstracted representation of such a location, and provides means for relative navigation. + ** The implementation involves a hidden service to record a movement trail, which allows to consider + ** the way how a some deeply nested scope was accessed. This information might be of relevance, due + ** to the ability to use _virtual clips_ recursively as part of the edit. Effectively, such means to + ** refer to some edit defined elsewhere in the session, and thus this feature turns the tree of nested + ** scopes into a *DAG* (directed acyclic graph). Such a structure can still be handled as if it was + ** a tree, but we need to take the access path into consideration: placing a given edit as virtual + ** clip into another scope will cause some properties not defined locally to be resolved in a + ** different way, depending on the context in which we encounter this virtual clip. To give an + ** example, the edited media might contain "sound", which needs to be panned and routed differently, + ** depending on the context the clip is placed into. + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef MOBJECT_SESSION_QUERY_FOCUS_H #define MOBJECT_SESSION_QUERY_FOCUS_H @@ -46,7 +69,7 @@ namespace session { * focus path locations. The intention is for this current location * to follow the ongoing query/discovery operations mostly automatically. * - * \par usage + * # usage * * A QueryFocus (frontend handle) can be default constructed, in which * case it will automatically connect to what is currently the focus diff --git a/src/proc/mobject/session/query/fake-configrules.cpp b/src/proc/mobject/session/query/fake-configrules.cpp index 79747f2a3..30c81ab7a 100644 --- a/src/proc/mobject/session/query/fake-configrules.cpp +++ b/src/proc/mobject/session/query/fake-configrules.cpp @@ -21,6 +21,21 @@ * *****************************************************/ +/** @file fake-configrules.cpp + ** Implementation of a fake query resolution service based on preconfigured answers. + ** Since we're not able to build or even integrate a real resolution engine for the time being, + ** we use a table of preconfigured answers, which allows us to handle the standard cases and + ** some additional unit test cases. + ** + ** Obviously this is a dirty hack, and the implementation is a pile of spaghetti code, + ** hastily bashed together to keep things going. Typically this fake code collaborates with + ** backdoor functions placed into otherwise not yet implemented facilities, to get past the + ** roadblock. For example, StructFactory::made4fake() + ** + ** @deprecated integrate a real resolution engine! /////////////////////////////////////////////////////////TICKET #710 + */ + + #include "proc/mobject/session/query/fake-configrules.hpp" #include "proc/mobject/session.hpp" @@ -37,7 +52,7 @@ using lib::Literal; using util::isnil; -//////////////////////////////////////////////////////////////////TICKET #710 : to be removed entirely in Alpha +/////////////////////////////////////////////////////////////////////////////////////////////////////////////TICKET #710 : to be removed entirely in Alpha namespace proc { namespace mobject { diff --git a/src/proc/mobject/session/relativelocation.cpp b/src/proc/mobject/session/relativelocation.cpp index 1d40b67ca..bcb2002d1 100644 --- a/src/proc/mobject/session/relativelocation.cpp +++ b/src/proc/mobject/session/relativelocation.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file relativelocation.cpp + ** LocatingPin (constraint) to attach media objects relative to each other + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #include "proc/mobject/session/relativelocation.hpp" #include "proc/mobject/mobject.hpp" diff --git a/src/proc/mobject/session/relativelocation.hpp b/src/proc/mobject/session/relativelocation.hpp index 09eb45bfe..d106b0751 100644 --- a/src/proc/mobject/session/relativelocation.hpp +++ b/src/proc/mobject/session/relativelocation.hpp @@ -21,6 +21,12 @@ */ +/** @file relativelocation.hpp + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #ifndef MOBJECT_SESSION_RELATIVELOCATION_H #define MOBJECT_SESSION_RELATIVELOCATION_H diff --git a/src/proc/mobject/session/root.cpp b/src/proc/mobject/session/root.cpp index 7131c40aa..4ed24cd2e 100644 --- a/src/proc/mobject/session/root.cpp +++ b/src/proc/mobject/session/root.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file root.cpp + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/root.hpp" #include "common/query/defs-manager.hpp" diff --git a/src/proc/mobject/session/root.hpp b/src/proc/mobject/session/root.hpp index c6294f96e..854dfc4d6 100644 --- a/src/proc/mobject/session/root.hpp +++ b/src/proc/mobject/session/root.hpp @@ -21,6 +21,19 @@ */ +/** @file root.hpp + ** MObject within the session to represent "the session itself". + ** The root object is used as anchor point when it comes to building, accessing + ** or displaying the whole session. Moreover, the placement used to attach the + ** Root MObejct into the session effectively represents the "global scope" -- any + ** constraint attached to this placement possibly effects any other object placed + ** anywhere within this global scope... + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef PROC_MOBJECT_SESSION_ROOT_H #define PROC_MOBJECT_SESSION_ROOT_H diff --git a/src/proc/mobject/session/scope-locator.hpp b/src/proc/mobject/session/scope-locator.hpp index 2042a19e7..0cd253c2f 100644 --- a/src/proc/mobject/session/scope-locator.hpp +++ b/src/proc/mobject/session/scope-locator.hpp @@ -21,6 +21,13 @@ */ +/** @file scope-locator.hpp + ** Service to build the notion of a _current location_ within the Sesison model + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef PROC_MOBJECT_SESSION_SCOPE_LOCATOR_H #define PROC_MOBJECT_SESSION_SCOPE_LOCATOR_H @@ -45,7 +52,7 @@ namespace session { /** * Singleton service establishing a link to relate * any compound of nested placement scopes to the current session - * and the \em current focus for querying and exploring this structure. + * and the _current focus_ for querying and exploring this structure. * While it is OK to use this service directly, clients usually would * prefer to use QueryFocus as a frontend. * diff --git a/src/proc/mobject/session/scope-path.cpp b/src/proc/mobject/session/scope-path.cpp index 4ebc6bd28..00c1f0266 100644 --- a/src/proc/mobject/session/scope-path.cpp +++ b/src/proc/mobject/session/scope-path.cpp @@ -21,6 +21,12 @@ * *****************************************************/ +/** @file scope-path.cpp + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "include/logging.h" #include "proc/mobject/session/scope-path.hpp" #include "proc/mobject/session/scope-locator.hpp" diff --git a/src/proc/mobject/session/scope.hpp b/src/proc/mobject/session/scope.hpp index a45ac7a74..f25eea594 100644 --- a/src/proc/mobject/session/scope.hpp +++ b/src/proc/mobject/session/scope.hpp @@ -21,6 +21,12 @@ */ +/** @file scope.hpp + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef PROC_MOBJECT_SESSION_SCOPE_H #define PROC_MOBJECT_SESSION_SCOPE_H diff --git a/src/proc/mobject/session/segment.cpp b/src/proc/mobject/session/segment.cpp index 9ef7e8a0d..9f601809a 100644 --- a/src/proc/mobject/session/segment.cpp +++ b/src/proc/mobject/session/segment.cpp @@ -20,6 +20,12 @@ * *****************************************************/ + +/** @file segment.cpp + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + #include "proc/mobject/session/segment.hpp" #include "proc/mobject/explicitplacement.hpp" diff --git a/src/proc/mobject/session/segment.hpp b/src/proc/mobject/session/segment.hpp index 593c81d94..7eba07412 100644 --- a/src/proc/mobject/session/segment.hpp +++ b/src/proc/mobject/session/segment.hpp @@ -21,6 +21,13 @@ */ +/** @file segment.hpp + ** Building block of the backbone of the low-level (render node) model + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #ifndef MOBJECT_SESSION_SEGMENT_H #define MOBJECT_SESSION_SEGMENT_H diff --git a/src/proc/mobject/session/segmentation.cpp b/src/proc/mobject/session/segmentation.cpp index 16bb9c1e4..0a8d9c721 100644 --- a/src/proc/mobject/session/segmentation.cpp +++ b/src/proc/mobject/session/segmentation.cpp @@ -20,6 +20,12 @@ * *****************************************************/ + +/** @file segmentation.cpp + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + #include "proc/mobject/session/segmentation.hpp" diff --git a/src/proc/mobject/session/segmentation.hpp b/src/proc/mobject/session/segmentation.hpp index 08dac8c93..047ced48b 100644 --- a/src/proc/mobject/session/segmentation.hpp +++ b/src/proc/mobject/session/segmentation.hpp @@ -21,6 +21,18 @@ */ +/** @file segmentation.hpp + ** A segment of the effective timeline, part of the low-level model backbone. + ** 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. + ** Moreover, the segments are used as foundation for render node memory management + ** + ** @todo stalled effort towards a session implementation from 2008 + ** @todo 2016 likely to stay, but expect some extensive rework + */ + + #ifndef MOBJECT_SESSION_SEGMENTATION_H #define MOBJECT_SESSION_SEGMENTATION_H diff --git a/src/proc/mobject/session/sess-manager-impl.cpp b/src/proc/mobject/session/sess-manager-impl.cpp index 87f8a73df..fac985f04 100644 --- a/src/proc/mobject/session/sess-manager-impl.cpp +++ b/src/proc/mobject/session/sess-manager-impl.cpp @@ -29,7 +29,7 @@ ** access via his overloaded operator->() . Because there is no operator*(), ** no one can get at the address of the current session object. (correct?) ** - ** TODO: this is an implementation draft, awaiting integration with several other facilities //////////////////TICKET #704 + ** @todo as of 2016 this is an implementation draft, awaiting integration with several other facilities //////////////////TICKET #704 ** ** @see session-impl.hpp ** @see mobject::Session#current diff --git a/src/proc/mobject/session/sess-manager-impl.hpp b/src/proc/mobject/session/sess-manager-impl.hpp index 59d6bf3e4..401fbc5be 100644 --- a/src/proc/mobject/session/sess-manager-impl.hpp +++ b/src/proc/mobject/session/sess-manager-impl.hpp @@ -21,6 +21,22 @@ */ +/** @file sess-manager-impl.hpp + ** Implementation facility for session management. + ** Users are assumed to access the session itself through a smart-ptr, which happens + ** to be the SessManager. Thus, accessing this front-end directly allows to invoke the + ** typical lifecycle and management operations (open, close, save, load). Since the + ** Session plays such a central role, we obviously want to expose just an interface + ** to client code, both regarding the Session itself, and the session manager. + ** + ** The SessManagerImpl involves the LifecylceAdvisor, which holds all the logic to + ** manage start-up and shutdown of the session, including starting of the core services + ** and opening of the external facade interfaces. + ** + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef MOBJECT_SESSION_SESS_MANAGER_IMPL_H #define MOBJECT_SESSION_SESS_MANAGER_IMPL_H diff --git a/src/proc/mobject/session/session-impl.cpp b/src/proc/mobject/session/session-impl.cpp index decf06612..40c00d68b 100644 --- a/src/proc/mobject/session/session-impl.cpp +++ b/src/proc/mobject/session/session-impl.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file session-impl.cpp + ** Implementation of the global session datastructure + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/session-impl.hpp" #include "proc/mobject/session/mobjectfactory.hpp" #include "proc/mobject/session/query-focus.hpp" diff --git a/src/proc/mobject/session/session-services.cpp b/src/proc/mobject/session/session-services.cpp index 5ab2470b1..167daefbb 100644 --- a/src/proc/mobject/session/session-services.cpp +++ b/src/proc/mobject/session/session-services.cpp @@ -21,6 +21,26 @@ * *****************************************************/ +/** @file session-services.cpp + ** Implementation of some top-level internal services of the session. + ** The Session is _the_ central interface to access the model and thus the + ** edit being worked on. Behind the scenes, it needs to operate several technically + ** quite involved services, which we prefer to hide away as implementation details. + ** Typically, each of these services defines a dedicated interface, and is implemented + ** by delegating to a set of more specialised facilities. + ** + ** The following services are integrated here + ** - service to access a Placement by (hash) ID + ** - service to attach or remove session content, while maintaining all indices + ** - service to query and explore session contents + ** - service to inject mock content for unit testing + ** - service to manage and discover default settings by resolution query + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #include "proc/mobject/session/session-service-fetch.hpp" #include "proc/mobject/session/session-service-mutate.hpp" #include "proc/mobject/session/session-service-explore-scope.hpp" diff --git a/src/proc/mobject/session/specific-contents-query.hpp b/src/proc/mobject/session/specific-contents-query.hpp index 531f8d067..08303fae3 100644 --- a/src/proc/mobject/session/specific-contents-query.hpp +++ b/src/proc/mobject/session/specific-contents-query.hpp @@ -21,6 +21,16 @@ */ +/** @file specific-contents-query.hpp + ** Implementation facility to query and retrieve session context with filtering conditions. + ** Client code is assumed to use the QueryResolver front-end and the SessionServiceExploreScope + ** as access point. + ** + ** @todo WIP implementation of session core from 2010 + ** @todo as of 2016, this effort is considered stalled but basically valid + */ + + #ifndef MOBJECT_SESSION_SPECIFIC_CONTENTS_QUERY_H #define MOBJECT_SESSION_SPECIFIC_CONTENTS_QUERY_H diff --git a/src/proc/mobject/session/wish.cpp b/src/proc/mobject/session/wish.cpp index 9973feee2..dd538ca65 100644 --- a/src/proc/mobject/session/wish.cpp +++ b/src/proc/mobject/session/wish.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file wish.cpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + */ + + #include "proc/mobject/session/wish.hpp" namespace proc { diff --git a/src/proc/mobject/session/wish.hpp b/src/proc/mobject/session/wish.hpp index 7040589f1..3b3c27392 100644 --- a/src/proc/mobject/session/wish.hpp +++ b/src/proc/mobject/session/wish.hpp @@ -21,6 +21,12 @@ */ +/** @file wish.hpp + ** @todo result of the very first code generation from UML in 2008. Relevance not clear yet... + ** @deprecated WTF? + */ + + #ifndef MOBJECT_SESSION_WISH_H #define MOBJECT_SESSION_WISH_H diff --git a/src/proc/play/dummy-play-connection.cpp b/src/proc/play/dummy-play-connection.cpp index 4be7d7a9f..2810726bf 100644 --- a/src/proc/play/dummy-play-connection.cpp +++ b/src/proc/play/dummy-play-connection.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file dummy-play-connection.cpp + ** Implementation of a service for mock render playback to support testing. + */ + + #include "proc/play/dummy-play-connection.hpp" //#include "proc/play/dummy-image-generator.hpp" //#include "proc/play/tick-service.hpp" diff --git a/src/proc/play/dummy-play-connection.hpp b/src/proc/play/dummy-play-connection.hpp index 3892b13ca..ff60ed45e 100644 --- a/src/proc/play/dummy-play-connection.hpp +++ b/src/proc/play/dummy-play-connection.hpp @@ -21,7 +21,7 @@ */ /** @file dummy-play-connection.hpp - ** Dummy and test setup of playback and rendering, \em omitting most of the Lumiera engine. + ** Dummy and test setup of playback and rendering, _omitting most_ of the Lumiera engine. ** Building this dummy configuration was driven by the need to test and verify the design ** in the course of building the foundations of the render engine. The design of Lumiera's ** engine is elaborate, and thus -- for a long time -- we have to live with a not-yet @@ -32,7 +32,7 @@ ** these placeholders are connected, allowing to produce specific test situations and then ** verify the results after the test run. ** - ** \par Use cases + ** # Use cases ** This dummy setup can be used in various circumstances ** - for unit tests we want to produce artificial test media frames: each TestFrame is ** produced with a reproducible pseudo-random sequence and can be verified to the last bit. @@ -44,16 +44,16 @@ ** to verify a more complicated wiring setup. Thus, the DummyPlayConnection is there to stay! ** ** Because these are somewhat similar usage scenarios, where this and that part is to be exchanged - ** for some, we prefer a policy based design here: The DummyPlayConnection is templated - ** to use a \em strategy, filling in the variable parts. + ** for some, we prefer a _policy based design_ here: The DummyPlayConnection is templated + ** to use _a strategy,_ filling in the variable parts. ** - ** \par provided test services + ** # provided test services ** By using different strategy template parameters, we create different flavours of the dummy; ** each one counting as a separate setup (not related to each other, that is). The actual instance ** then can just be default created; it should be placed into an scope enduring the whole usage ** cycle. Repeated re-initialisation or re-loading is outside the intended usage scope here. ** - ** The core interface allows to retrieve dummy implementations of + ** The *core interface* allows to retrieve dummy implementations of ** - a session model exposing exit node(s) ** - generator object(s) to live within this session model ** - corresponding generator nodes to serve as implementation of the former @@ -61,7 +61,7 @@ ** - OutputSlot implementations to serve as pseudo- or demo output facilities ** - an OutputManager exposing those output facilities. ** - ** The test support interface provides a test driver for performing a controlled + ** The *test support interface* provides a test driver for performing a controlled ** playback or rendering for some time. Thus, a test routine may lock into a blocking wait, ** to investigate results after the planned test sequence was performed. ** @@ -132,10 +132,10 @@ namespace play { // using lib::ScopedCollection; // using lib::Literal; using lib::eachEntry; - + typedef asset::ID PID; typedef asset::ID TID; - + // typedef ModelPortRegistry::ModelPortDescriptor const& MPDescriptor; @@ -156,7 +156,7 @@ namespace play { const string namePortB("bus-B"); /** - * helper for dummy render engine: + * helper for dummy render engine: * Simulate the result of a build process, * without actually running the builder. * Produces some mock pipes, model ports etc. @@ -211,7 +211,7 @@ namespace play { } }; } - + /****************************************************************//** * Framework for dummy playback and rendering. @@ -279,4 +279,4 @@ namespace play { }} // namespace proc::play -#endif +#endif /*PROC_PLAY_DUMMY_PLAY_CONNECTION_H*/ diff --git a/src/proc/play/dummy-player-interface-proxy.hpp b/src/proc/play/dummy-player-interface-proxy.hpp index 46df53188..a4db2b95b 100644 --- a/src/proc/play/dummy-player-interface-proxy.hpp +++ b/src/proc/play/dummy-player-interface-proxy.hpp @@ -54,6 +54,7 @@ //#include "proc/play/dummy-player-service.hpp" #include "include/dummy-player-facade.h" +#include "include/interfaceproxy.hpp" namespace lumiera { diff --git a/src/proc/play/dummy-player-service.cpp b/src/proc/play/dummy-player-service.cpp index a18b23b09..737d7ebd7 100644 --- a/src/proc/play/dummy-player-service.cpp +++ b/src/proc/play/dummy-player-service.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file dummy-player-service.cpp + ** Implementation of a service for mock render output to support testing. + */ + + #include "proc/play/dummy-player-service.hpp" #include "proc/engine/worker/dummy-image-generator.hpp" #include "proc/engine/worker/tick-service.hpp" diff --git a/src/proc/play/output-director.cpp b/src/proc/play/output-director.cpp index a8a5aafcd..d27c4270b 100644 --- a/src/proc/play/output-director.cpp +++ b/src/proc/play/output-director.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file output-director.cpp + ** Implementation of global output connection management + */ + + #include "proc/play/play-service.hpp" #include "proc/play/output-manager.hpp" #include "proc/play/output-director.hpp" diff --git a/src/proc/play/output-slot.cpp b/src/proc/play/output-slot.cpp index e063aaf81..15e50f999 100644 --- a/src/proc/play/output-slot.cpp +++ b/src/proc/play/output-slot.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file output-slot.cpp + ** Generic implementation functionality common to all output connections. + */ + + #include "lib/error.hpp" #include "proc/play/output-slot.hpp" #include "proc/play/output-slot-connection.hpp" diff --git a/src/proc/play/output-slot.hpp b/src/proc/play/output-slot.hpp index 3dbfe87d5..87d685dad 100644 --- a/src/proc/play/output-slot.hpp +++ b/src/proc/play/output-slot.hpp @@ -32,7 +32,7 @@ ** external output, or a group of such outputs (e.g. left and right sound card output channels), ** or an output file or similar capability accepting media content. Initially, an output slot ** needs to be provided, configured and registered, using an implementation suitable for the - ** kind of media data to be output (sound, video) and also suitable for the special circumstances + ** kind of media data to be sent (sound, video) and also suitable for the special circumstances ** of the output capability (render a file, display video in a GUI widget, send video to some ** full screen display, establish a Jack port, just use some kind of "sound out"). An output ** slot is always limited to a single kind of media, and to a single connection unit, but @@ -43,16 +43,16 @@ ** there may be only a single client using a given output slot this way. To stress this point: ** output slots don't provide any kind of inherent mixing capability; any adaptation, mixing, ** overlaying and sharing needs to be done within the nodes network producing the output data - ** to be fed into the slot. (in special cases, some external output capabilities — e.g. the - ** Jack audio connection system — may still provide additional mixing capabilities, + ** to be fed into the slot. (in special cases, some external output capabilities -- e.g. the + ** Jack audio connection system -- may still provide additional mixing capabilities, ** but that's beyond the scope of the Lumiera application) ** ** Once allocated, the output slot returns a set of concrete sink handles (one for each ** physical channel expecting data). The calculating process feeds its results into those handles. ** Size and other characteristics of the data frames are assumed to be suitable, which typically ** won't be verified at that level anymore. Besides that, the allocation of an output slot reveals - ** detailed timing expectations. The client is required to comply to these timings when \em emitting - ** data — he's even required to provide a current time specification, alongside with the data. + ** detailed timing expectations. The client is required to comply to these timings when _emitting_ + ** data -- he's even required to provide a current time specification, alongside with the data. ** Based on this information, the output slot has the ability to handle timing failures gracefully; ** the concrete output slot implementation is expected to provide some kind of de-click or ** de-flicker facility, which kicks in automatically when a timing failure is detected. diff --git a/src/proc/play/play-process.cpp b/src/proc/play/play-process.cpp index 09676a8ae..4317e4ddc 100644 --- a/src/proc/play/play-process.cpp +++ b/src/proc/play/play-process.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file play-process.cpp + ** Implementation to organise an ongoing playback/rendering process + */ + + #include "proc/play/play-process.hpp" #include "proc/play/play-service.hpp" #include "proc/play/render-configurator.hpp" diff --git a/src/proc/play/play-service.cpp b/src/proc/play/play-service.cpp index 32aa3f250..3a1e7b001 100644 --- a/src/proc/play/play-service.cpp +++ b/src/proc/play/play-service.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file play-service.cpp + ** Implementation of core parts of the Player subsystem + */ + + #include "lib/error.hpp" #include "include/play-facade.h" #include "proc/play/play-service.hpp" diff --git a/src/proc/play/play-service.hpp b/src/proc/play/play-service.hpp index 37756123b..2dcf103d8 100644 --- a/src/proc/play/play-service.hpp +++ b/src/proc/play/play-service.hpp @@ -30,12 +30,12 @@ ** of the High-Level-Model). These model ports are the (side effect) result of a ** build process performed on the High-Level-Model, causing all nominal output ** designations within the model to be resolved as far as possible. Additionally, - ** for \em playback, the global level of the model (the global pipes of a timeline) + ** for _playback,_ the global level of the model (the global pipes of a timeline) ** need to be connected to a viewer component. This results in a further resolution ** step, mapping the output designations to the concrete output possibilities of ** the running Lumiera instance. This mapping information is kept embedded within ** an OutputManager instance, passed as parameter when invoking the player service. - ** Alternatively, for \em rendering, a similar kind of output mapping information + ** Alternatively, for _rendering,_ a similar kind of output mapping information ** needs to be provided, again embedded within an OutputManager instance, this ** time leading to an output file to be rendered. ** @@ -46,7 +46,8 @@ ** the scenes the corresponding PlayProcess gets terminated and prepared for cleanup. ** ** @see engine::EngineService - ** @todo WIP-WIP-WIP as of Nov.2011 + ** @todo started as draft in 11/2011 + ** @todo as of 2016 development in this area is stalled, but the design done thus far valid ** */ diff --git a/src/proc/play/render-configurator.cpp b/src/proc/play/render-configurator.cpp index 37383ec5d..73521fcdb 100644 --- a/src/proc/play/render-configurator.cpp +++ b/src/proc/play/render-configurator.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file render-configurator.cpp + ** Implementation functionality to bridge between engine::PlayService and engine::EngineService. + ** The former allows to start playback (or rendering) as a high-level activity, while the latter + ** can manage and perform [calculation streams](\ref CalcStream) + */ + + #include "lib/error.hpp" #include "proc/play/render-configurator.hpp" #include "proc/play/output-manager.hpp" diff --git a/src/proc/play/render-configurator.hpp b/src/proc/play/render-configurator.hpp index 8c5f7159d..85b868b36 100644 --- a/src/proc/play/render-configurator.hpp +++ b/src/proc/play/render-configurator.hpp @@ -21,7 +21,7 @@ */ /** @file render-configurator.hpp - ** Strategy holding all the detail knowledge necessary to establish + ** Strategy to hold all the detail knowledge necessary to establish ** a running render CalculationStream. ** ** @see engine::EngineService diff --git a/src/proc/play/sound/jack-output.cpp b/src/proc/play/sound/jack-output.cpp index 4fc576d0d..85f857387 100644 --- a/src/proc/play/sound/jack-output.cpp +++ b/src/proc/play/sound/jack-output.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file jack-output.cpp + ** + ** @todo empty placeholder: yes we will support Jack Audio! + ** + */ + + #include "proc/play/sound/jack-output.hpp" namespace proc { diff --git a/src/proc/play/sound/jack-output.hpp b/src/proc/play/sound/jack-output.hpp index d793662d3..4aa50f4d2 100644 --- a/src/proc/play/sound/jack-output.hpp +++ b/src/proc/play/sound/jack-output.hpp @@ -21,7 +21,9 @@ */ /** @file jack-output.hpp - ** + ** + ** @todo empty placeholder to underpin the claim: yes we will support Jack Audio! + ** ** @see lumiera::Display ** @see lumiera::DummyPlayer ** @see gui::PlaybackController usage example diff --git a/src/proc/play/timings.cpp b/src/proc/play/timings.cpp index de12984d6..b3b631502 100644 --- a/src/proc/play/timings.cpp +++ b/src/proc/play/timings.cpp @@ -21,6 +21,15 @@ * *****************************************************/ +/** @file timings.cpp + ** Implementation of a data tuple for timing specification. + ** A Timings record represents a constraint on playback, and will be + ** used to organise and the calculations necessary to generate the data. + ** Especially, a Timings record serves to establish a relation to an externally + ** fixed time grid or time source. + */ + + #include "proc/play/timings.hpp" #include "backend/engine/engine-config.h" #include "lib/time/formats.hpp" diff --git a/src/proc/state.cpp b/src/proc/state.cpp deleted file mode 100644 index 15dc9ba3a..000000000 --- a/src/proc/state.cpp +++ /dev/null @@ -1,33 +0,0 @@ -/* - State - Key Interface representing a render process and encapsulating state - - Copyright (C) Lumiera.org - 2008, Hermann Vosseler - - 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. - -* *****************************************************/ - - -#include "proc/state.hpp" - -namespace proc_interface { - - ////////////////////////////////TODO: State is a high -level interface, so can we get rid of this implementation file? - /** */ - - - -} // namespace proc_interface diff --git a/src/proc/state.hpp b/src/proc/state.hpp index e2e7414f4..618b71b7b 100644 --- a/src/proc/state.hpp +++ b/src/proc/state.hpp @@ -21,6 +21,11 @@ */ +/** @file state.hpp + ** Access point to an ongoing render's processing state. + */ + + #ifndef PROC_INTERFACE_STATE_H #define PROC_INTERFACE_STATE_H @@ -43,10 +48,10 @@ namespace engine { /** - * Abstraction denoting the state of a currently ongoing render/calculation - * process, as it is tied to the supporting facilities of the backend. - * An State (subclass) instance is the sole connection for the render node - * to invoke services of the backend needed to carry out the calculations. + * Abstraction to access the state of a currently ongoing render/calculation process, + * as it is tied to the supporting facilities of the backend. An State (subclass) instance + * is the sole connection for the render node to invoke services of the backend needed + * to carry out the calculations. * * @see engine::RenderInvocation top-level entrance point * @see nodeinvocation.hpp impl. used from \em within the nodes diff --git a/src/proc/streamtype.cpp b/src/proc/streamtype.cpp index 0213ba211..272390fb9 100644 --- a/src/proc/streamtype.cpp +++ b/src/proc/streamtype.cpp @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file streamtype.cpp + ** Implementation of a _stream type_ framework + */ + + #include "proc/streamtype.hpp" diff --git a/src/tool/alsa.c b/src/tool/alsa.c index 68969f49a..83cd839c7 100644 --- a/src/tool/alsa.c +++ b/src/tool/alsa.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file alsa.c + ** Example implementation how to access the ALSA sound backend + */ + + #include "alsa.h" #include diff --git a/src/tool/alsa.h b/src/tool/alsa.h index 30fdb75f7..082ed8388 100644 --- a/src/tool/alsa.h +++ b/src/tool/alsa.h @@ -22,6 +22,7 @@ /** @file alsa.h ** Interfacing to ALSA sound output. + ** @remarks Example implementation from 2011 ** ** @todo for now this header defines some functions used for experimentation with ALSA ** diff --git a/src/tool/hello.c b/src/tool/hello.c index 43b3c3291..471efc0c9 100644 --- a/src/tool/hello.c +++ b/src/tool/hello.c @@ -3,6 +3,11 @@ * integrated into the SCons based build system of Lumiera */ + +/** @file hello.c + ** Example file to demonstrate integration of stand-alone tools into the build process + */ + #include int diff --git a/src/tool/main.c b/src/tool/main.c index 86a027b41..d0e096b64 100644 --- a/src/tool/main.c +++ b/src/tool/main.c @@ -21,6 +21,14 @@ * *****************************************************/ +/** @file main.c + ** A stand alone application to test integration with output frameworks + ** @remarks the plan was to evolve this into a command line tool eventually, + ** which would use Lumiera's backend functionality to setup and probe + ** the operation environment for diagnostic purpose + */ + + #include "alsa.h" #include diff --git a/src/tool/rsvg-convert.c b/src/tool/rsvg-convert.c index eee28cc07..0bcb905ac 100644 --- a/src/tool/rsvg-convert.c +++ b/src/tool/rsvg-convert.c @@ -24,6 +24,14 @@ * *****************************************************/ +/** @file rsvg-convert.c + ** Invoke the rSVG library to render SVG vector graphics with the help of Cairo. + ** @note This tool is tightly integrated into the Lumiera build process in order + ** to render icons and UI decorations designed as vector graphics, for those + ** cases where it is beneficial to use bitmap graphics within the UI toolkit. + */ + + #ifndef N_ #define N_(X) X #endif diff --git a/tests/backend/sync-classlock-test.cpp b/tests/backend/sync-classlock-test.cpp index 8eace7879..f8389dd22 100644 --- a/tests/backend/sync-classlock-test.cpp +++ b/tests/backend/sync-classlock-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sync-classlock-test.cpp + ** unit test \ref SyncClasslock_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/backend/sync-locking-test.cpp b/tests/backend/sync-locking-test.cpp index eab82cf44..2bf1aea69 100644 --- a/tests/backend/sync-locking-test.cpp +++ b/tests/backend/sync-locking-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sync-locking-test.cpp + ** unit test \ref SyncLocking_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/backend/sync-timedwait-test.cpp b/tests/backend/sync-timedwait-test.cpp index 2aef282a0..d0e15361f 100644 --- a/tests/backend/sync-timedwait-test.cpp +++ b/tests/backend/sync-timedwait-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sync-timedwait-test.cpp + ** unit test \ref SyncTimedwait_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/backend/sync-waiting-test.cpp b/tests/backend/sync-waiting-test.cpp index 2e2004b76..8533c3c28 100644 --- a/tests/backend/sync-waiting-test.cpp +++ b/tests/backend/sync-waiting-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sync-waiting-test.cpp + ** unit test \ref SyncWaiting_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/backend/test-filedescriptors.c b/tests/backend/test-filedescriptors.c index 11fb41390..904228dac 100644 --- a/tests/backend/test-filedescriptors.c +++ b/tests/backend/test-filedescriptors.c @@ -1,5 +1,5 @@ /* - TEST-FILEDESCRIPTORS + TEST-FILEDESCRIPTORS - verify filedescriptor management Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-filedescriptors.c + ** C unit test to cover filedescriptor management + ** @see filedescriptor.h + */ + #include "lib/safeclib.h" diff --git a/tests/backend/test-filehandles.c b/tests/backend/test-filehandles.c index 9abc38fad..83da58793 100644 --- a/tests/backend/test-filehandles.c +++ b/tests/backend/test-filehandles.c @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-filehandles.c + ** C unit test to cover management for filehandles and the filehandle cache + ** @see filehandlecache.h + */ + #include "lib/llist.h" #include "lib/tmpbuf.h" diff --git a/tests/backend/test-fileheader.c b/tests/backend/test-fileheader.c index 960680602..70985b67c 100644 --- a/tests/backend/test-fileheader.c +++ b/tests/backend/test-fileheader.c @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-fileheader.c + ** C unit test to verify file identification functions + ** @see fileheader.h + */ + #include "backend/backend.h" #include "backend/fileheader.h" diff --git a/tests/backend/test-filemmap.c b/tests/backend/test-filemmap.c index 31abae0f9..4a2159ec1 100644 --- a/tests/backend/test-filemmap.c +++ b/tests/backend/test-filemmap.c @@ -1,5 +1,5 @@ /* - TEST-FILEMAP - test file management + TEST-FILEMAP - test file memory mapping Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-filemmap.c + ** C unit test to cover memory mapping of file contents + ** @see mmapings.h + */ + //#include //#include diff --git a/tests/backend/test-resourcecollector.c b/tests/backend/test-resourcecollector.c index b6809cf07..b55ec115f 100644 --- a/tests/backend/test-resourcecollector.c +++ b/tests/backend/test-resourcecollector.c @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-resourcecollector.c + ** C unit test to cover management of low-level resources for the backend + ** @see resourcecollector.h + */ + #include "backend/resourcecollector.h" diff --git a/tests/backend/test-threadpool.c b/tests/backend/test-threadpool.c index 807dc1d66..9320b94c5 100644 --- a/tests/backend/test-threadpool.c +++ b/tests/backend/test-threadpool.c @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-threadpool.c + ** C unit test to cover our threadpool implementation + */ + #include "lib/test/test.h" diff --git a/tests/backend/test-threads.c b/tests/backend/test-threads.c index 23de08ec3..395680d0e 100644 --- a/tests/backend/test-threads.c +++ b/tests/backend/test-threads.c @@ -20,6 +20,14 @@ * *****************************************************/ +/** @file test-threads.c + ** C unit test to cover thread handling helpers + ** Especially, we rely on a specific setup for threads, which allows + ** to manage worker threads in a threadpool + ** @see threads.h + ** @see test-threadpool.c + */ + //#include //#include diff --git a/tests/backend/thread-local-test.cpp b/tests/backend/thread-local-test.cpp index 4cbd895c3..78ff14bc6 100644 --- a/tests/backend/thread-local-test.cpp +++ b/tests/backend/thread-local-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file thread-local-test.cpp + ** unit test \ref ThreadLocal_test + */ + #include "lib/test/run.hpp" diff --git a/tests/backend/thread-wrapper-join-test.cpp b/tests/backend/thread-wrapper-join-test.cpp index dbfffa286..f96935c6e 100644 --- a/tests/backend/thread-wrapper-join-test.cpp +++ b/tests/backend/thread-wrapper-join-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file thread-wrapper-join-test.cpp + ** unit test \ref ThreadWrapperJoin_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/backend/thread-wrapper-test.cpp b/tests/backend/thread-wrapper-test.cpp index 6f643a5fd..55b165d47 100644 --- a/tests/backend/thread-wrapper-test.cpp +++ b/tests/backend/thread-wrapper-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file thread-wrapper-test.cpp + ** unit test \ref ThreadWrapper_test + */ + #include "lib/test/run.hpp" diff --git a/tests/basics/diagnostic-context-test.cpp b/tests/basics/diagnostic-context-test.cpp index 2f1168bee..723ad2589 100644 --- a/tests/basics/diagnostic-context-test.cpp +++ b/tests/basics/diagnostic-context-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file diagnostic-context-test.cpp + ** unit test \ref DiagnosticContext_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/streamtypebasicstest.cpp b/tests/basics/stream-type-basics-test.cpp similarity index 97% rename from tests/basics/streamtypebasicstest.cpp rename to tests/basics/stream-type-basics-test.cpp index a211248ac..5b295c516 100644 --- a/tests/basics/streamtypebasicstest.cpp +++ b/tests/basics/stream-type-basics-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file streamtypebasicstest.cpp + ** unit test \ref StreamTypeBasics_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/basics/streamtypelifecycletest.cpp b/tests/basics/stream-type-lifecycle-test.cpp similarity index 97% rename from tests/basics/streamtypelifecycletest.cpp rename to tests/basics/stream-type-lifecycle-test.cpp index ea69e7324..a27e0405e 100644 --- a/tests/basics/streamtypelifecycletest.cpp +++ b/tests/basics/stream-type-lifecycle-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file streamtypelifecycletest.cpp + ** unit test \ref StreamTypeLifecycle_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/basics/teststreamtypes.hpp b/tests/basics/teststreamtypes.hpp index db22fe9cb..bcb96df35 100644 --- a/tests/basics/teststreamtypes.hpp +++ b/tests/basics/teststreamtypes.hpp @@ -20,6 +20,10 @@ */ +/** @file teststreamtypes.hpp + ** Unit test helper to create fake streamtype information + */ + #ifndef LUMIERA_TEST_TESTSTREAMTYPES_H #define LUMIERA_TEST_TESTSTREAMTYPES_H diff --git a/tests/basics/time/digxel-configurations-test.cpp b/tests/basics/time/digxel-configurations-test.cpp index 60a9de713..12d0858a3 100644 --- a/tests/basics/time/digxel-configurations-test.cpp +++ b/tests/basics/time/digxel-configurations-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file digxel-configurations-test.cpp + ** unit test \ref DigxelConfigurations_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/digxel-test.cpp b/tests/basics/time/digxel-test.cpp index 2a3a78936..f8eb7efc5 100644 --- a/tests/basics/time/digxel-test.cpp +++ b/tests/basics/time/digxel-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file digxel-test.cpp + ** unit test \ref Digxel_test + */ + #include "lib/test/run.hpp" #include "lib/format-cout.hpp" diff --git a/tests/basics/time/format-support-test.cpp b/tests/basics/time/format-support-test.cpp index b1f90465d..d2e57c729 100644 --- a/tests/basics/time/format-support-test.cpp +++ b/tests/basics/time/format-support-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file format-support-test.cpp + ** unit test \ref FormatSupport_test + */ + #include "lib/test/run.hpp" #include "lib/time/formats.hpp" diff --git a/tests/basics/time/quantiser-basics-test.cpp b/tests/basics/time/quantiser-basics-test.cpp index edc4ced6a..c93da9370 100644 --- a/tests/basics/time/quantiser-basics-test.cpp +++ b/tests/basics/time/quantiser-basics-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file quantiser-basics-test.cpp + ** unit test \ref QuantiserBasics_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/time-basics-test.cpp b/tests/basics/time/time-basics-test.cpp index 4e1cd3b99..e8bf048b5 100644 --- a/tests/basics/time/time-basics-test.cpp +++ b/tests/basics/time/time-basics-test.cpp @@ -1,5 +1,5 @@ /* - LumiBasics(Test) - working with Lumiera's internal Time values + TimeBasics(Test) - working with Lumiera's internal Time values Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-basics-test.cpp + ** unit test \ref TimeBasics_test + */ + #include "lib/test/run.hpp" #include "lib/time/timevalue.hpp" diff --git a/tests/basics/time/time-control-test.cpp b/tests/basics/time/time-control-test.cpp index b2e878eae..624c211d0 100644 --- a/tests/basics/time/time-control-test.cpp +++ b/tests/basics/time/time-control-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-control-test.cpp + ** unit test \ref TimeControl_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/time-formats-test.cpp b/tests/basics/time/time-formats-test.cpp index c04dd22a6..041f8abfd 100644 --- a/tests/basics/time/time-formats-test.cpp +++ b/tests/basics/time/time-formats-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-formats-test.cpp + ** unit test \ref TimeFormats_test + */ + #include "lib/test/run.hpp" //#include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/time-mutation-test.cpp b/tests/basics/time/time-mutation-test.cpp index eef879f35..c0701c05f 100644 --- a/tests/basics/time/time-mutation-test.cpp +++ b/tests/basics/time/time-mutation-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-mutation-test.cpp + ** unit test \ref TimeMutation_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/time-parsing-test.cpp b/tests/basics/time/time-parsing-test.cpp index ddb2acd4f..499b4efd5 100644 --- a/tests/basics/time/time-parsing-test.cpp +++ b/tests/basics/time/time-parsing-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-parsing-test.cpp + ** unit test \ref TimeParsing_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/time-quantisation-test.cpp b/tests/basics/time/time-quantisation-test.cpp index 24eff8eb6..517b9bfc8 100644 --- a/tests/basics/time/time-quantisation-test.cpp +++ b/tests/basics/time/time-quantisation-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-quantisation-test.cpp + ** unit test \ref TimeQuantisation_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/time/time-value-test.cpp b/tests/basics/time/time-value-test.cpp index d26a7cc8e..bf9b1a13e 100644 --- a/tests/basics/time/time-value-test.cpp +++ b/tests/basics/time/time-value-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-value-test.cpp + ** unit test \ref TimeValue_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/basics/visitingtool-extended-test.cpp b/tests/basics/visitingtool-extended-test.cpp index 85e79b882..13d21bebd 100644 --- a/tests/basics/visitingtool-extended-test.cpp +++ b/tests/basics/visitingtool-extended-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file visitingtool-extended-test.cpp + ** unit test \ref VisitingToolExtended_test + */ + #include "lib/test/run.hpp" #include "lib/visitor.hpp" diff --git a/tests/basics/visitingtool-test.cpp b/tests/basics/visitingtool-test.cpp index a868aa3a8..9c6b7c655 100644 --- a/tests/basics/visitingtool-test.cpp +++ b/tests/basics/visitingtool-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file visitingtool-test.cpp + ** unit test \ref VisitingTool_test + */ + #include "lib/test/run.hpp" #include "lib/visitor.hpp" diff --git a/tests/core/application/subsystem-runner-test.cpp b/tests/core/application/subsystem-runner-test.cpp index 6b3594c8a..84678420a 100644 --- a/tests/core/application/subsystem-runner-test.cpp +++ b/tests/core/application/subsystem-runner-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file subsystem-runner-test.cpp + ** unit test \ref SubsystemRunner_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/application/test-configloader.c b/tests/core/application/test-configloader.c index 9af8b7b18..bfd75a7e7 100644 --- a/tests/core/application/test-configloader.c +++ b/tests/core/application/test-configloader.c @@ -21,6 +21,11 @@ * *****************************************************/ +/** @file test-configloader.c + ** C unit test to cover a config system draft implementation + ** @deprecated as of 2017 it is very likely we'll use a different approach + */ + #include "lib/tmpbuf.h" diff --git a/tests/core/application/test-interfaces.c b/tests/core/application/test-interfaces.c index c6cefe06f..bbae36bf5 100644 --- a/tests/core/application/test-interfaces.c +++ b/tests/core/application/test-interfaces.c @@ -20,6 +20,12 @@ * *****************************************************/ +/** @file test-interfaces.c + ** C unit test to cover the basics of our interface and plugin-loading system + ** @see interface.h + ** @see interfaceregistry.h + */ + #include "common/interface.h" #include "common/interfaceregistry.h" @@ -28,7 +34,7 @@ #include "common/config-interface.h" #include "lib/test/test.h" -#include "interface/say_hello.h" +#include "interface/say-hello.h" /* define 2 example interfaces diff --git a/tests/core/backend/engine/dummy-job.cpp b/tests/core/backend/engine/dummy-job.cpp index 029cdaf7f..1b69ad09e 100644 --- a/tests/core/backend/engine/dummy-job.cpp +++ b/tests/core/backend/engine/dummy-job.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file dummy-job.cpp + ** Implementation of a dummy render job for unit tests + */ + #include "backend/engine/dummy-job.hpp" diff --git a/tests/core/backend/engine/dummy-job.hpp b/tests/core/backend/engine/dummy-job.hpp index 102085926..b18571e10 100644 --- a/tests/core/backend/engine/dummy-job.hpp +++ b/tests/core/backend/engine/dummy-job.hpp @@ -20,6 +20,10 @@ */ +/** @file dummy-job.hpp + ** Unit test helper to generate dummy render jobs + */ + #ifndef BACKEND_ENGINE_DUMMY_JOB_H #define BACKEND_ENGINE_DUMMY_JOB_H diff --git a/tests/core/backend/engine/job-hash-test.cpp b/tests/core/backend/engine/job-hash-test.cpp index e73002cc3..41f2fe21b 100644 --- a/tests/core/backend/engine/job-hash-test.cpp +++ b/tests/core/backend/engine/job-hash-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file job-hash-test.cpp + ** unit test \ref JobHash_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/core/backend/engine/scheduler-interface-test.cpp b/tests/core/backend/engine/scheduler-interface-test.cpp index 46704ad20..adc03ea0f 100644 --- a/tests/core/backend/engine/scheduler-interface-test.cpp +++ b/tests/core/backend/engine/scheduler-interface-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scheduler-interface-test.cpp + ** unit test \ref SchedulerInterface_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/core/backend/media-access-mock-test.cpp b/tests/core/backend/media-access-mock-test.cpp index 6b316b9e6..6d4113bb8 100644 --- a/tests/core/backend/media-access-mock-test.cpp +++ b/tests/core/backend/media-access-mock-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file media-access-mock-test.cpp + ** unit test \ref MediaAccessMock_test + */ + #include "backend/media-access-facade.hpp" #include "backend/media-access-mock.hpp" diff --git a/tests/core/backend/media-access-mock.hpp b/tests/core/backend/media-access-mock.hpp index c44e61b3c..f44e9060e 100644 --- a/tests/core/backend/media-access-mock.hpp +++ b/tests/core/backend/media-access-mock.hpp @@ -20,6 +20,14 @@ */ +/** @file media-access-mock.hpp + ** Unit test helper to access an emulated media file. + ** This can be used to inject specific metadata or media properties, + ** or even to feed generated media content into the code to be tested. + ** + ** @todo this facility was occasionally used until 2011, yet never really completed + */ + #ifndef BACKEND_TEST_MEDIA_ACCESS_MOCK_H #define BACKEND_TEST_MEDIA_ACCESS_MOCK_H diff --git a/tests/core/proc/asset/asset-category-test.cpp b/tests/core/proc/asset/asset-category-test.cpp index 86f4e9a64..b209eff6b 100644 --- a/tests/core/proc/asset/asset-category-test.cpp +++ b/tests/core/proc/asset/asset-category-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file asset-category-test.cpp + ** unit test \ref AssetCategory_test + */ + #include "lib/test/run.hpp" #include "lib/format-cout.hpp" diff --git a/tests/core/proc/asset/basicpipetest.cpp b/tests/core/proc/asset/basicpipetest.cpp index b20910eed..476619c66 100644 --- a/tests/core/proc/asset/basicpipetest.cpp +++ b/tests/core/proc/asset/basicpipetest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file basicpipetest.cpp + ** unit test \ref BasicPipe_test + */ + #include "include/logging.h" #include "lib/test/run.hpp" diff --git a/tests/core/proc/asset/compoundmediatest.cpp b/tests/core/proc/asset/compoundmediatest.cpp index b63ce29f6..b2f5a9cb7 100644 --- a/tests/core/proc/asset/compoundmediatest.cpp +++ b/tests/core/proc/asset/compoundmediatest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file compoundmediatest.cpp + ** unit test \ref CompoundMedia_test + */ + #include "include/logging.h" #include "lib/test/run.hpp" diff --git a/tests/core/proc/asset/create-asset-test.cpp b/tests/core/proc/asset/create-asset-test.cpp index 7d54201b6..100530366 100644 --- a/tests/core/proc/asset/create-asset-test.cpp +++ b/tests/core/proc/asset/create-asset-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file create-asset-test.cpp + ** unit test \ref CreateAsset_test + */ + #include "include/logging.h" #include "lib/test/run.hpp" diff --git a/tests/core/proc/asset/deleteassettest.cpp b/tests/core/proc/asset/deleteassettest.cpp index a03d30356..6b3a3fb51 100644 --- a/tests/core/proc/asset/deleteassettest.cpp +++ b/tests/core/proc/asset/deleteassettest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file deleteassettest.cpp + ** unit test \ref DeleteAsset_test + */ + #include "lib/test/run.hpp" //#include "lib/util.hpp" diff --git a/tests/core/proc/asset/dependent-assets-test.cpp b/tests/core/proc/asset/dependent-assets-test.cpp index 7ba5a0a33..6d5eb8077 100644 --- a/tests/core/proc/asset/dependent-assets-test.cpp +++ b/tests/core/proc/asset/dependent-assets-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file dependent-assets-test.cpp + ** unit test \ref DependentAssets_test + */ + #include "lib/test/run.hpp" #include "proc/asset/testasset.hpp" diff --git a/tests/core/proc/asset/entry-id-test.cpp b/tests/core/proc/asset/entry-id-test.cpp index 4f58cbb23..516253de8 100644 --- a/tests/core/proc/asset/entry-id-test.cpp +++ b/tests/core/proc/asset/entry-id-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file entry-id-test.cpp + ** unit test \ref EntryID_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/asset/identityofassetstest.cpp b/tests/core/proc/asset/identity-of-assets-test.cpp similarity index 97% rename from tests/core/proc/asset/identityofassetstest.cpp rename to tests/core/proc/asset/identity-of-assets-test.cpp index 226b472c5..40e705e08 100644 --- a/tests/core/proc/asset/identityofassetstest.cpp +++ b/tests/core/proc/asset/identity-of-assets-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file identityofassetstest.cpp + ** unit test \ref IdentityOfAssets_test + */ + #include "include/logging.h" #include "lib/test/run.hpp" diff --git a/tests/core/proc/asset/makecliptest.cpp b/tests/core/proc/asset/make-clip-test.cpp similarity index 97% rename from tests/core/proc/asset/makecliptest.cpp rename to tests/core/proc/asset/make-clip-test.cpp index 1b556d36f..070aa5ff0 100644 --- a/tests/core/proc/asset/makecliptest.cpp +++ b/tests/core/proc/asset/make-clip-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file makecliptest.cpp + ** unit test \ref MakeClip_test + */ + #include "include/logging.h" #include "lib/test/run.hpp" diff --git a/tests/core/proc/asset/mediastructurequerytest.cpp b/tests/core/proc/asset/media-structure-query-test.cpp similarity index 91% rename from tests/core/proc/asset/mediastructurequerytest.cpp rename to tests/core/proc/asset/media-structure-query-test.cpp index 4f6397e84..9251be8fb 100644 --- a/tests/core/proc/asset/mediastructurequerytest.cpp +++ b/tests/core/proc/asset/media-structure-query-test.cpp @@ -1,5 +1,5 @@ /* - MediaStructureQuery(Test) - check functionallity used for creating media assets + MediaStructureQuery(Test) - check functionality used for creating media assets Copyright (C) Lumiera.org 2008, Hermann Vosseler @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file mediastructurequerytest.cpp + ** unit test \ref MediaStructureQuery_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/core/proc/asset/meta/time-grid-basics-test.cpp b/tests/core/proc/asset/meta/time-grid-basics-test.cpp index 5d4d47beb..a5cae3e7c 100644 --- a/tests/core/proc/asset/meta/time-grid-basics-test.cpp +++ b/tests/core/proc/asset/meta/time-grid-basics-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file time-grid-basics-test.cpp + ** unit test \ref TimeGridBasics_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/asset/orderingofassetstest.cpp b/tests/core/proc/asset/ordering-of-assets-test.cpp similarity index 98% rename from tests/core/proc/asset/orderingofassetstest.cpp rename to tests/core/proc/asset/ordering-of-assets-test.cpp index 849bc9890..35ee89786 100644 --- a/tests/core/proc/asset/orderingofassetstest.cpp +++ b/tests/core/proc/asset/ordering-of-assets-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file orderingofassetstest.cpp + ** unit test \ref OrderingOfAssets_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/core/proc/asset/testasset.cpp b/tests/core/proc/asset/testasset.cpp index 7213852f5..e0ea5ce5a 100644 --- a/tests/core/proc/asset/testasset.cpp +++ b/tests/core/proc/asset/testasset.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file testasset.cpp + ** Implementation of a mocked Asset for unit tests + */ + #include "proc/asset/testasset.hpp" #include "proc/assetmanager.hpp" diff --git a/tests/core/proc/asset/testasset.hpp b/tests/core/proc/asset/testasset.hpp index 413eb2f58..50e958a74 100644 --- a/tests/core/proc/asset/testasset.hpp +++ b/tests/core/proc/asset/testasset.hpp @@ -20,6 +20,10 @@ */ +/** @file testasset.hpp + ** A mock asset to support unit testing + */ + #ifndef ASSET_TESTASSET_H #define ASSET_TESTASSET_H diff --git a/tests/core/proc/asset/testclipasset.hpp b/tests/core/proc/asset/testclipasset.hpp index 4d0ca97c9..b10925925 100644 --- a/tests/core/proc/asset/testclipasset.hpp +++ b/tests/core/proc/asset/testclipasset.hpp @@ -20,6 +20,10 @@ */ +/** @file testclipasset.hpp + ** A placeholder Clip asset to support unit testing + */ + #ifndef ASSET_TESTCLIPASSET_H #define ASSET_TESTCLIPASSET_H diff --git a/tests/core/proc/asset/typed-id-test.cpp b/tests/core/proc/asset/typed-id-test.cpp index ae2c80977..7fdc569f3 100644 --- a/tests/core/proc/asset/typed-id-test.cpp +++ b/tests/core/proc/asset/typed-id-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file typed-id-test.cpp + ** unit test \ref TypedID_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/argument-tuple-accept-test.cpp b/tests/core/proc/control/argument-tuple-accept-test.cpp index f328a6540..317508ecb 100644 --- a/tests/core/proc/control/argument-tuple-accept-test.cpp +++ b/tests/core/proc/control/argument-tuple-accept-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file argument-tuple-accept-test.cpp + ** unit test \ref ArgumentTupleAccept_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-argument-test.cpp b/tests/core/proc/control/command-argument-test.cpp index 2421067ef..e5b80c827 100644 --- a/tests/core/proc/control/command-argument-test.cpp +++ b/tests/core/proc/control/command-argument-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-argument-test.cpp + ** unit test \ref CommandArgument_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-basic-test.cpp b/tests/core/proc/control/command-basic-test.cpp index 49054e798..51a6e5ae3 100644 --- a/tests/core/proc/control/command-basic-test.cpp +++ b/tests/core/proc/control/command-basic-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-basic-test.cpp + ** unit test \ref CommandBasic_test + */ + #include "lib/test/run.hpp" #include "proc/control/command-def.hpp" diff --git a/tests/core/proc/control/command-binding-test.cpp b/tests/core/proc/control/command-binding-test.cpp index 549137d2a..e224f7803 100644 --- a/tests/core/proc/control/command-binding-test.cpp +++ b/tests/core/proc/control/command-binding-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-binding-test.cpp + ** unit test \ref CommandBinding_test + */ + #include "lib/test/run.hpp" #include "proc/control/command-def.hpp" diff --git a/tests/core/proc/control/command-clone-builder-test.cpp b/tests/core/proc/control/command-clone-builder-test.cpp index 266a877f7..86a881dea 100644 --- a/tests/core/proc/control/command-clone-builder-test.cpp +++ b/tests/core/proc/control/command-clone-builder-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-clone-builder-test.cpp + ** unit test \ref CommandCloneBuilder_test + */ + #include "lib/test/run.hpp" #include "proc/control/command-impl.hpp" diff --git a/tests/core/proc/control/command-equality-test.cpp b/tests/core/proc/control/command-equality-test.cpp index 9cfe98fbe..1486806d3 100644 --- a/tests/core/proc/control/command-equality-test.cpp +++ b/tests/core/proc/control/command-equality-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-equality-test.cpp + ** unit test \ref CommandEquality_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-message-binding-test.cpp b/tests/core/proc/control/command-message-binding-test.cpp index a694fe424..77efb53cb 100644 --- a/tests/core/proc/control/command-message-binding-test.cpp +++ b/tests/core/proc/control/command-message-binding-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-message-binding-test.cpp + ** unit test \ref CommandMessageBinding_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-mutation-test.cpp b/tests/core/proc/control/command-mutation-test.cpp index 85354b2a3..52b811010 100644 --- a/tests/core/proc/control/command-mutation-test.cpp +++ b/tests/core/proc/control/command-mutation-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-mutation-test.cpp + ** unit test \ref CommandMutation_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-registry-test.cpp b/tests/core/proc/control/command-registry-test.cpp index 17bbc5b59..b137284e4 100644 --- a/tests/core/proc/control/command-registry-test.cpp +++ b/tests/core/proc/control/command-registry-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-registry-test.cpp + ** unit test \ref CommandRegistry_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-use1-test.cpp b/tests/core/proc/control/command-use1-test.cpp index 4e87538d1..f288063dd 100644 --- a/tests/core/proc/control/command-use1-test.cpp +++ b/tests/core/proc/control/command-use1-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-use1-test.cpp + ** unit test \ref CommandUse1_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-use2-test.cpp b/tests/core/proc/control/command-use2-test.cpp index 7f82cd23c..b2b07edf1 100644 --- a/tests/core/proc/control/command-use2-test.cpp +++ b/tests/core/proc/control/command-use2-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-use2-test.cpp + ** unit test \ref CommandUse2_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/command-use3-test.cpp b/tests/core/proc/control/command-use3-test.cpp index 350fdb936..eafb74e60 100644 --- a/tests/core/proc/control/command-use3-test.cpp +++ b/tests/core/proc/control/command-use3-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file command-use3-test.cpp + ** unit test \ref CommandUse3_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/handling-pattern-basics-test.cpp b/tests/core/proc/control/handling-pattern-basics-test.cpp index 004c47dc7..a3d24f658 100644 --- a/tests/core/proc/control/handling-pattern-basics-test.cpp +++ b/tests/core/proc/control/handling-pattern-basics-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file handling-pattern-basics-test.cpp + ** unit test \ref HandlingPatternBasics_test + */ + #include "lib/test/run.hpp" #include "proc/control/command.hpp" diff --git a/tests/core/proc/control/handling-pattern-standard-impl-test.cpp b/tests/core/proc/control/handling-pattern-standard-impl-test.cpp index 3e9c04320..42a44241e 100644 --- a/tests/core/proc/control/handling-pattern-standard-impl-test.cpp +++ b/tests/core/proc/control/handling-pattern-standard-impl-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file handling-pattern-standard-impl-test.cpp + ** unit test \ref HandlingPatternStandardImpl_test + */ + #include "lib/test/run.hpp" //#include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/memento-tie-test.cpp b/tests/core/proc/control/memento-tie-test.cpp index aea4af164..c26c75411 100644 --- a/tests/core/proc/control/memento-tie-test.cpp +++ b/tests/core/proc/control/memento-tie-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file memento-tie-test.cpp + ** unit test \ref MementoTie_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/control/test-dummy-commands.cpp b/tests/core/proc/control/test-dummy-commands.cpp index 138855f82..79af6e3f6 100644 --- a/tests/core/proc/control/test-dummy-commands.cpp +++ b/tests/core/proc/control/test-dummy-commands.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-dummy-commands.cpp + ** Implementation of dummy command operations for unit tests + */ + #include "proc/control/test-dummy-commands.hpp" #include "proc/control/command-def.hpp" diff --git a/tests/core/proc/engine/buff-table-test.cpp b/tests/core/proc/engine/buff-table-test.cpp index 49901ccbf..f09a88055 100644 --- a/tests/core/proc/engine/buff-table-test.cpp +++ b/tests/core/proc/engine/buff-table-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file buff-table-test.cpp + ** unit test \ref BuffTable_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/core/proc/engine/buffer-metadata-key-test.cpp b/tests/core/proc/engine/buffer-metadata-key-test.cpp index 1da4525b8..69479057c 100644 --- a/tests/core/proc/engine/buffer-metadata-key-test.cpp +++ b/tests/core/proc/engine/buffer-metadata-key-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file buffer-metadata-key-test.cpp + ** unit test \ref BufferMetadataKey_test + */ + #include "lib/error.hpp" #include "lib/test/run.hpp" diff --git a/tests/core/proc/engine/buffer-metadata-test.cpp b/tests/core/proc/engine/buffer-metadata-test.cpp index e390e5955..3888358a5 100644 --- a/tests/core/proc/engine/buffer-metadata-test.cpp +++ b/tests/core/proc/engine/buffer-metadata-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file buffer-metadata-test.cpp + ** unit test \ref BufferMetadata_test + */ + #include "lib/error.hpp" #include "lib/test/run.hpp" diff --git a/tests/core/proc/engine/buffer-provider-protocol-test.cpp b/tests/core/proc/engine/buffer-provider-protocol-test.cpp index af53d51e3..0c269aba5 100644 --- a/tests/core/proc/engine/buffer-provider-protocol-test.cpp +++ b/tests/core/proc/engine/buffer-provider-protocol-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file buffer-provider-protocol-test.cpp + ** unit test \ref BufferProviderProtocol_test + */ + #include "lib/error.hpp" #include "lib/test/run.hpp" diff --git a/tests/core/proc/engine/calc-stream-test.cpp b/tests/core/proc/engine/calc-stream-test.cpp index 4a7a94cbf..641377aa1 100644 --- a/tests/core/proc/engine/calc-stream-test.cpp +++ b/tests/core/proc/engine/calc-stream-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file calc-stream-test.cpp + ** unit test \ref CalcStream_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/core/proc/engine/dispatcher-interface-test.cpp b/tests/core/proc/engine/dispatcher-interface-test.cpp index 0993e23d3..6abd9efce 100644 --- a/tests/core/proc/engine/dispatcher-interface-test.cpp +++ b/tests/core/proc/engine/dispatcher-interface-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file dispatcher-interface-test.cpp + ** unit test \ref DispatcherInterface_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/core/proc/engine/engine-interface-test.cpp b/tests/core/proc/engine/engine-interface-test.cpp index ba2818977..b3916afca 100644 --- a/tests/core/proc/engine/engine-interface-test.cpp +++ b/tests/core/proc/engine/engine-interface-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file engine-interface-test.cpp + ** unit test \ref EngineInterface_test + */ + #include "lib/test/run.hpp" #include "lib/error.hpp" diff --git a/tests/core/proc/engine/node-basic-test.cpp b/tests/core/proc/engine/node-basic-test.cpp index 56a61a16a..36ef79b76 100644 --- a/tests/core/proc/engine/node-basic-test.cpp +++ b/tests/core/proc/engine/node-basic-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file node-basic-test.cpp + ** unit test \ref NodeBasic_test + */ + #include "lib/test/run.hpp" #include "proc/engine/nodefactory.hpp" diff --git a/tests/core/proc/engine/node-fabrication-test.cpp b/tests/core/proc/engine/node-fabrication-test.cpp index a4fef5324..78a2500ca 100644 --- a/tests/core/proc/engine/node-fabrication-test.cpp +++ b/tests/core/proc/engine/node-fabrication-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file node-fabrication-test.cpp + ** unit test \ref NodeFabrication_test + */ + #include "lib/test/run.hpp" //#include "lib/util.hpp" diff --git a/tests/core/proc/engine/node-operation-test.cpp b/tests/core/proc/engine/node-operation-test.cpp index 0e3a7e3f4..65930421b 100644 --- a/tests/core/proc/engine/node-operation-test.cpp +++ b/tests/core/proc/engine/node-operation-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file node-operation-test.cpp + ** unit test \ref NodeOperation_test + */ + #include "lib/test/run.hpp" //#include "lib/util.hpp" diff --git a/tests/core/proc/engine/node-source-test.cpp b/tests/core/proc/engine/node-source-test.cpp index a722e052d..1b4a95390 100644 --- a/tests/core/proc/engine/node-source-test.cpp +++ b/tests/core/proc/engine/node-source-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file node-source-test.cpp + ** unit test \ref NodeSource_test + */ + #include "lib/test/run.hpp" //#include "lib/util.hpp" diff --git a/tests/core/proc/engine/testframe-test.cpp b/tests/core/proc/engine/testframe-test.cpp index d5da47da9..aa87eac00 100644 --- a/tests/core/proc/engine/testframe-test.cpp +++ b/tests/core/proc/engine/testframe-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file testframe-test.cpp + ** unit test \ref TestFrame_test + */ + #include "lib/test/run.hpp" #include "proc/engine/testframe.hpp" diff --git a/tests/core/proc/engine/testframe.cpp b/tests/core/proc/engine/testframe.cpp index 254309aec..9b4b5048a 100644 --- a/tests/core/proc/engine/testframe.cpp +++ b/tests/core/proc/engine/testframe.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file testframe.cpp + ** Implementation of fake data frames to support unit testing + */ + #include "proc/engine/testframe.hpp" #include "lib/error.hpp" diff --git a/tests/core/proc/engine/testframe.hpp b/tests/core/proc/engine/testframe.hpp index 05cfecff8..e39be683e 100644 --- a/tests/core/proc/engine/testframe.hpp +++ b/tests/core/proc/engine/testframe.hpp @@ -20,6 +20,10 @@ */ +/** @file testframe.hpp + ** Unit test helper to generate fake test data frames + */ + #ifndef PROC_ENGINE_TESTFRAME_H #define PROC_ENGINE_TESTFRAME_H diff --git a/tests/core/proc/engine/tracking-heap-block-provider-test.cpp b/tests/core/proc/engine/tracking-heap-block-provider-test.cpp index 79aa9ffd2..50b2a83e7 100644 --- a/tests/core/proc/engine/tracking-heap-block-provider-test.cpp +++ b/tests/core/proc/engine/tracking-heap-block-provider-test.cpp @@ -1,4 +1,4 @@ -/*u4 +/* TrackingHeapBlockProvider(Test) - verify a support facility for diagnostic/test purposes Copyright (C) Lumiera.org @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file tracking-heap-block-provider-test.cpp + ** unit test \ref TrackingHeapBlockProvider_test + */ + #include "lib/error.hpp" #include "lib/test/run.hpp" diff --git a/tests/core/proc/mobject/builder/buildsegmenttest.cpp b/tests/core/proc/mobject/builder/build-segment-test.cpp similarity index 95% rename from tests/core/proc/mobject/builder/buildsegmenttest.cpp rename to tests/core/proc/mobject/builder/build-segment-test.cpp index 95bd3b2c0..0d2c26ada 100644 --- a/tests/core/proc/mobject/builder/buildsegmenttest.cpp +++ b/tests/core/proc/mobject/builder/build-segment-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file buildsegmenttest.cpp + ** unit test \ref BuildSegment_test + */ + #include "lib/test/run.hpp" //#include "lib/util.hpp" diff --git a/tests/core/proc/mobject/builder/buildertooltest.cpp b/tests/core/proc/mobject/builder/builder-tool-test.cpp similarity index 98% rename from tests/core/proc/mobject/builder/buildertooltest.cpp rename to tests/core/proc/mobject/builder/builder-tool-test.cpp index 8ac47cf24..d8e46cf87 100644 --- a/tests/core/proc/mobject/builder/buildertooltest.cpp +++ b/tests/core/proc/mobject/builder/builder-tool-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file buildertooltest.cpp + ** unit test \ref BuilderTool_test + */ + #include "lib/test/run.hpp" diff --git a/tests/core/proc/mobject/builder/fixture-change-detector-test.cpp b/tests/core/proc/mobject/builder/fixture-change-detector-test.cpp index 1f0397242..71b344efc 100644 --- a/tests/core/proc/mobject/builder/fixture-change-detector-test.cpp +++ b/tests/core/proc/mobject/builder/fixture-change-detector-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file fixture-change-detector-test.cpp + ** unit test \ref FixtureChangeDetector_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" @@ -83,7 +87,8 @@ namespace test { /*****************************************************************************//** - * @test TODO blubb + * @test planned test for detecting changes in a given segmentation + * @todo just a placeholder, nothing done here thus far (2016) * * @see mobject::builder::FixtureChangeDetector */ diff --git a/tests/core/proc/mobject/builder/model-port-registry-test.cpp b/tests/core/proc/mobject/builder/model-port-registry-test.cpp index 1d47fb689..6fd756434 100644 --- a/tests/core/proc/mobject/builder/model-port-registry-test.cpp +++ b/tests/core/proc/mobject/builder/model-port-registry-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file model-port-registry-test.cpp + ** unit test \ref ModelPortRegistry_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/builder/segmentation-datastructure-test.cpp b/tests/core/proc/mobject/builder/segmentation-datastructure-test.cpp index 6bf35fbd8..b517e554b 100644 --- a/tests/core/proc/mobject/builder/segmentation-datastructure-test.cpp +++ b/tests/core/proc/mobject/builder/segmentation-datastructure-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file segmentation-datastructure-test.cpp + ** unit test \ref SegmentationDatastructure_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/controller/rendersegmenttest.cpp b/tests/core/proc/mobject/controller/render-segment-test.cpp similarity index 96% rename from tests/core/proc/mobject/controller/rendersegmenttest.cpp rename to tests/core/proc/mobject/controller/render-segment-test.cpp index 7b148c3e9..189499b44 100644 --- a/tests/core/proc/mobject/controller/rendersegmenttest.cpp +++ b/tests/core/proc/mobject/controller/render-segment-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file rendersegmenttest.cpp + ** unit test \ref RenderSegment_test + */ + #include "lib/test/run.hpp" //#include "lib/util.hpp" diff --git a/tests/core/proc/mobject/mobject-interface-test.cpp b/tests/core/proc/mobject/mobject-interface-test.cpp index 4a78cf813..698db1e7f 100644 --- a/tests/core/proc/mobject/mobject-interface-test.cpp +++ b/tests/core/proc/mobject/mobject-interface-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file mobject-interface-test.cpp + ** unit test \ref MObjectInterface_test + */ + #include "lib/test/run.hpp" #include "lib/symbol.hpp" diff --git a/tests/core/proc/mobject/mobject-ref-test.cpp b/tests/core/proc/mobject/mobject-ref-test.cpp index 2b7469e9b..364d01e8e 100644 --- a/tests/core/proc/mobject/mobject-ref-test.cpp +++ b/tests/core/proc/mobject/mobject-ref-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file mobject-ref-test.cpp + ** unit test \ref MObjectRef_test + */ + #include "lib/test/run.hpp" #include "proc/asset/media.hpp" diff --git a/tests/core/proc/mobject/output-mapping-test.cpp b/tests/core/proc/mobject/output-mapping-test.cpp index 6dec6103a..0b15714f1 100644 --- a/tests/core/proc/mobject/output-mapping-test.cpp +++ b/tests/core/proc/mobject/output-mapping-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file output-mapping-test.cpp + ** unit test \ref OutputMapping_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/placement-basic-test.cpp b/tests/core/proc/mobject/placement-basic-test.cpp index b4edf1c0a..6bb2d89ac 100644 --- a/tests/core/proc/mobject/placement-basic-test.cpp +++ b/tests/core/proc/mobject/placement-basic-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-basic-test.cpp + ** unit test \ref PlacementBasic_test + */ + #include "lib/test/run.hpp" #include "proc/asset/media.hpp" diff --git a/tests/core/proc/mobject/placement-hierarchy-test.cpp b/tests/core/proc/mobject/placement-hierarchy-test.cpp index a2f667267..a04d266a9 100644 --- a/tests/core/proc/mobject/placement-hierarchy-test.cpp +++ b/tests/core/proc/mobject/placement-hierarchy-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-hierarchy-test.cpp + ** unit test \ref PlacementHierarchy_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/placement-object-identity-test.cpp b/tests/core/proc/mobject/placement-object-identity-test.cpp index 1de776ff6..e2a83b948 100644 --- a/tests/core/proc/mobject/placement-object-identity-test.cpp +++ b/tests/core/proc/mobject/placement-object-identity-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-object-identity-test.cpp + ** unit test \ref PlacementObjectIdentity_test + */ + #include "lib/test/run.hpp" #include "proc/asset/media.hpp" diff --git a/tests/core/proc/mobject/placement-ref-test.cpp b/tests/core/proc/mobject/placement-ref-test.cpp index b3c984ff7..38e642c3f 100644 --- a/tests/core/proc/mobject/placement-ref-test.cpp +++ b/tests/core/proc/mobject/placement-ref-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-ref-test.cpp + ** unit test \ref PlacementRef_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/session/addcliptest.cpp b/tests/core/proc/mobject/session/add-clip-test.cpp similarity index 96% rename from tests/core/proc/mobject/session/addcliptest.cpp rename to tests/core/proc/mobject/session/add-clip-test.cpp index 0f05faac2..2dd96bb45 100644 --- a/tests/core/proc/mobject/session/addcliptest.cpp +++ b/tests/core/proc/mobject/session/add-clip-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file addcliptest.cpp + ** unit test \ref AddClip_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/mobject/session/defs-manager-impl-test.cpp b/tests/core/proc/mobject/session/defs-manager-impl-test.cpp index 83f88776f..6289cd192 100644 --- a/tests/core/proc/mobject/session/defs-manager-impl-test.cpp +++ b/tests/core/proc/mobject/session/defs-manager-impl-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file defs-manager-impl-test.cpp + ** unit test \ref DefsManagerImpl_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/core/proc/mobject/session/defs-manager-test.cpp b/tests/core/proc/mobject/session/defs-manager-test.cpp index 60d29dc31..a7db7369e 100644 --- a/tests/core/proc/mobject/session/defs-manager-test.cpp +++ b/tests/core/proc/mobject/session/defs-manager-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file defs-manager-test.cpp + ** unit test \ref DefsManager_test + */ + #include "lib/test/run.hpp" #include "lib/symbol.hpp" diff --git a/tests/core/proc/mobject/session/defs-registry-impl-test.cpp b/tests/core/proc/mobject/session/defs-registry-impl-test.cpp index 158bb46a1..3822635fd 100644 --- a/tests/core/proc/mobject/session/defs-registry-impl-test.cpp +++ b/tests/core/proc/mobject/session/defs-registry-impl-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file defs-registry-impl-test.cpp + ** unit test \ref DefsRegistryImpl_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/core/proc/mobject/session/deletecliptest.cpp b/tests/core/proc/mobject/session/deletecliptest.cpp index 63600cdac..a744c2336 100644 --- a/tests/core/proc/mobject/session/deletecliptest.cpp +++ b/tests/core/proc/mobject/session/deletecliptest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file deletecliptest.cpp + ** unit test \ref DeleteClip_test + */ + #include "lib/test/run.hpp" #include "proc/assetmanager.hpp" diff --git a/tests/core/proc/mobject/session/placement-index-query-test.cpp b/tests/core/proc/mobject/session/placement-index-query-test.cpp index c0d451224..b6409908f 100644 --- a/tests/core/proc/mobject/session/placement-index-query-test.cpp +++ b/tests/core/proc/mobject/session/placement-index-query-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-index-query-test.cpp + ** unit test \ref PlacementIndexQuery_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session/scope-query.hpp" diff --git a/tests/core/proc/mobject/session/placement-index-test.cpp b/tests/core/proc/mobject/session/placement-index-test.cpp index 62c8baebe..85cddf015 100644 --- a/tests/core/proc/mobject/session/placement-index-test.cpp +++ b/tests/core/proc/mobject/session/placement-index-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-index-test.cpp + ** unit test \ref PlacementIndex_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/session/placement-scope-test.cpp b/tests/core/proc/mobject/session/placement-scope-test.cpp index 2d8e7e8ee..01ae4e1c9 100644 --- a/tests/core/proc/mobject/session/placement-scope-test.cpp +++ b/tests/core/proc/mobject/session/placement-scope-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file placement-scope-test.cpp + ** unit test \ref PlacementScope_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/session/query-focus-stack-test.cpp b/tests/core/proc/mobject/session/query-focus-stack-test.cpp index 5a58fe445..a98280ffa 100644 --- a/tests/core/proc/mobject/session/query-focus-stack-test.cpp +++ b/tests/core/proc/mobject/session/query-focus-stack-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file query-focus-stack-test.cpp + ** unit test \ref QueryFocusStack_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/session/query-focus-test.cpp b/tests/core/proc/mobject/session/query-focus-test.cpp index 129ed0388..36b86372f 100644 --- a/tests/core/proc/mobject/session/query-focus-test.cpp +++ b/tests/core/proc/mobject/session/query-focus-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file query-focus-test.cpp + ** unit test \ref QueryFocus_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session/test-scopes.hpp" diff --git a/tests/core/proc/mobject/session/query-resolver-test.cpp b/tests/core/proc/mobject/session/query-resolver-test.cpp index b23ddb513..0e8e29519 100644 --- a/tests/core/proc/mobject/session/query-resolver-test.cpp +++ b/tests/core/proc/mobject/session/query-resolver-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file query-resolver-test.cpp + ** unit test \ref QueryResolver_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/session/rebuildfixturetest.cpp b/tests/core/proc/mobject/session/rebuildfixturetest.cpp index 72053aa82..08ef95834 100644 --- a/tests/core/proc/mobject/session/rebuildfixturetest.cpp +++ b/tests/core/proc/mobject/session/rebuildfixturetest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file rebuildfixturetest.cpp + ** unit test \ref RebuildFixture_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/mobject/session/scope-path-test.cpp b/tests/core/proc/mobject/session/scope-path-test.cpp index 87957790a..18e760999 100644 --- a/tests/core/proc/mobject/session/scope-path-test.cpp +++ b/tests/core/proc/mobject/session/scope-path-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scope-path-test.cpp + ** unit test \ref ScopePath_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/core/proc/mobject/session/scope-query-test.cpp b/tests/core/proc/mobject/session/scope-query-test.cpp index 4c55546fc..c2206eae1 100644 --- a/tests/core/proc/mobject/session/scope-query-test.cpp +++ b/tests/core/proc/mobject/session/scope-query-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scope-query-test.cpp + ** unit test \ref ScopeQuery_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session/scope-query.hpp" diff --git a/tests/core/proc/mobject/session/session-element-query-test.cpp b/tests/core/proc/mobject/session/session-element-query-test.cpp index df647c77d..b75c54394 100644 --- a/tests/core/proc/mobject/session/session-element-query-test.cpp +++ b/tests/core/proc/mobject/session/session-element-query-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file session-element-query-test.cpp + ** unit test \ref SessionElementQuery_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session/test-scopes.hpp" diff --git a/tests/core/proc/mobject/session/session-element-tracker-test.cpp b/tests/core/proc/mobject/session/session-element-tracker-test.cpp index bd236cf3d..503141f49 100644 --- a/tests/core/proc/mobject/session/session-element-tracker-test.cpp +++ b/tests/core/proc/mobject/session/session-element-tracker-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file session-element-tracker-test.cpp + ** unit test \ref SessionElementTracker_test + */ + #include "lib/test/run.hpp" diff --git a/tests/core/proc/mobject/session/sessionmanagertest.cpp b/tests/core/proc/mobject/session/session-manager-test.cpp similarity index 98% rename from tests/core/proc/mobject/session/sessionmanagertest.cpp rename to tests/core/proc/mobject/session/session-manager-test.cpp index 8468e84b1..b02dad02c 100644 --- a/tests/core/proc/mobject/session/sessionmanagertest.cpp +++ b/tests/core/proc/mobject/session/session-manager-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sessionmanagertest.cpp + ** unit test \ref SessionManager_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/mobject/session/session-modify-parts-test.cpp b/tests/core/proc/mobject/session/session-modify-parts-test.cpp index 14c9cad8b..dabf20f79 100644 --- a/tests/core/proc/mobject/session/session-modify-parts-test.cpp +++ b/tests/core/proc/mobject/session/session-modify-parts-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file session-modify-parts-test.cpp + ** unit test \ref SessionModifyParts_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/mobject/session/session-service-access-test.cpp b/tests/core/proc/mobject/session/session-service-access-test.cpp index 64c9eaf44..ecb837c7f 100644 --- a/tests/core/proc/mobject/session/session-service-access-test.cpp +++ b/tests/core/proc/mobject/session/session-service-access-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file session-service-access-test.cpp + ** unit test \ref SessionServiceAccess_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/mobject/session/session-structure-test.cpp b/tests/core/proc/mobject/session/session-structure-test.cpp index 37d741bbb..e3d2ee0bf 100644 --- a/tests/core/proc/mobject/session/session-structure-test.cpp +++ b/tests/core/proc/mobject/session/session-structure-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file session-structure-test.cpp + ** unit test \ref SessionStructure_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/mobject/session/test-scope-invalid.hpp b/tests/core/proc/mobject/session/test-scope-invalid.hpp index cadc0267a..b0a1849f6 100644 --- a/tests/core/proc/mobject/session/test-scope-invalid.hpp +++ b/tests/core/proc/mobject/session/test-scope-invalid.hpp @@ -20,6 +20,11 @@ */ +/** @file test-scope-invalid.hpp + ** Unit test helper to generate deliberately wrong placement scopes. + ** Usable to cover error handling related to QueryFocus and ScopePath + */ + #ifndef MOBJECT_SESSION_TEST_SCOPE_INVALID_H #define MOBJECT_SESSION_TEST_SCOPE_INVALID_H diff --git a/tests/core/proc/mobject/session/test-scopes.cpp b/tests/core/proc/mobject/session/test-scopes.cpp index 4b08e1339..b7374d926 100644 --- a/tests/core/proc/mobject/session/test-scopes.cpp +++ b/tests/core/proc/mobject/session/test-scopes.cpp @@ -20,6 +20,12 @@ * *****************************************************/ +/** @file test-scopes.cpp + ** Implementation of nested test scopes to cover the placement index. + ** This translation unit builds mock "session content" with a fixed, known layout, + ** which can be used to verify the behaviour of session query and content discovery + */ + #include "proc/mobject/session/test-scopes.hpp" #include "proc/mobject/session/session-service-mock-index.hpp" diff --git a/tests/core/proc/mobject/session/test-scopes.hpp b/tests/core/proc/mobject/session/test-scopes.hpp index f1e1a60fc..eb9d49d77 100644 --- a/tests/core/proc/mobject/session/test-scopes.hpp +++ b/tests/core/proc/mobject/session/test-scopes.hpp @@ -20,6 +20,13 @@ */ +/** @file test-scopes.hpp + ** Unit test helper to generate a system of nested test scopes. + ** These can be used to verify session search and discovery functionality. + ** The build_testScopes() function generates a system of placements and MObjects + ** with a known, fixed layout. + */ + #ifndef MOBJECT_SESSION_TEST_TEST_SCOPES_H #define MOBJECT_SESSION_TEST_TEST_SCOPES_H diff --git a/tests/core/proc/mobject/session/testclip.cpp b/tests/core/proc/mobject/session/testclip.cpp index 79c276aa5..9edd7df3f 100644 --- a/tests/core/proc/mobject/session/testclip.cpp +++ b/tests/core/proc/mobject/session/testclip.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file testclip.cpp + ** Implementation of a stubbed clip object to support unit testing + */ + #include "proc/mobject/session/testclip.hpp" #include "backend/media-access-facade.hpp" diff --git a/tests/core/proc/mobject/session/testclip.hpp b/tests/core/proc/mobject/session/testclip.hpp index 0f3179620..dcd3adef1 100644 --- a/tests/core/proc/mobject/session/testclip.hpp +++ b/tests/core/proc/mobject/session/testclip.hpp @@ -20,6 +20,10 @@ */ +/** @file testclip.hpp + ** A stub implementation of the Clip interface for unit testing + */ + #ifndef MOBJECT_SESSION_TESTCLIP_H #define MOBJECT_SESSION_TESTCLIP_H diff --git a/tests/core/proc/mobject/session/testroot.hpp b/tests/core/proc/mobject/session/testroot.hpp index bbbd2d8e8..93d539d3b 100644 --- a/tests/core/proc/mobject/session/testroot.hpp +++ b/tests/core/proc/mobject/session/testroot.hpp @@ -20,6 +20,12 @@ */ +/** @file testroot.hpp + ** Setup of a faked session root for unit testing. + ** This works together with some likewise manipulated mock rules to build content + ** with known layout to be scrutinised in test + */ + #ifndef MOBJECT_SESSION_TESTROOT_H #define MOBJECT_SESSION_TESTROOT_H diff --git a/tests/core/proc/mobject/session/testsession1.hpp b/tests/core/proc/mobject/session/testsession1.hpp index 10490d14c..1d47c7ea7 100644 --- a/tests/core/proc/mobject/session/testsession1.hpp +++ b/tests/core/proc/mobject/session/testsession1.hpp @@ -20,6 +20,13 @@ */ +/** @file testsession1.hpp + ** Dummy session content prepared for unit test + ** @todo this is an idea from the early stages of the project and was never really implemented. + ** But it still seems like a good idea (as of 2016), while likely the implementation will be + ** completely different, based on JSON to be injected via the diff system + */ + #ifndef MOBJECT_SESSION_TESTSESSION1_H #define MOBJECT_SESSION_TESTSESSION1_H diff --git a/tests/core/proc/mobject/session/timeline-sequence-handling-test.cpp b/tests/core/proc/mobject/session/timeline-sequence-handling-test.cpp index 044c675c4..6249055fe 100644 --- a/tests/core/proc/mobject/session/timeline-sequence-handling-test.cpp +++ b/tests/core/proc/mobject/session/timeline-sequence-handling-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file timeline-sequence-handling-test.cpp + ** unit test \ref TimelineSequenceHandling_test + */ + #include "lib/test/run.hpp" #include "proc/mobject/session.hpp" diff --git a/tests/core/proc/play/dummy-play-connection-test.cpp b/tests/core/proc/play/dummy-play-connection-test.cpp index c9e0f1777..1d4ee4685 100644 --- a/tests/core/proc/play/dummy-play-connection-test.cpp +++ b/tests/core/proc/play/dummy-play-connection-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file dummy-play-connection-test.cpp + ** unit test \ref DummyPlayConnection_test + */ + #include "lib/test/run.hpp" diff --git a/tests/core/proc/play/output-slot-protocol-test.cpp b/tests/core/proc/play/output-slot-protocol-test.cpp index 739a920d4..46fa21097 100644 --- a/tests/core/proc/play/output-slot-protocol-test.cpp +++ b/tests/core/proc/play/output-slot-protocol-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file output-slot-protocol-test.cpp + ** unit test \ref OutputSlotProtocol_test + */ + #include "lib/test/run.hpp" diff --git a/tests/core/proc/play/timing-constraints-test.cpp b/tests/core/proc/play/timing-constraints-test.cpp index 99b890798..14bca2d2f 100644 --- a/tests/core/proc/play/timing-constraints-test.cpp +++ b/tests/core/proc/play/timing-constraints-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file timing-constraints-test.cpp + ** unit test \ref TimingConstraints_test + */ + #include "lib/test/run.hpp" diff --git a/tests/gui/bus-term-test.cpp b/tests/gui/bus-term-test.cpp index 2a1fa7e45..505ccb03a 100644 --- a/tests/gui/bus-term-test.cpp +++ b/tests/gui/bus-term-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file bus-term-test.cpp + ** unit test \ref BusTerm_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/gui/interact/state-map-grouping-storage-test.cpp b/tests/gui/interact/state-map-grouping-storage-test.cpp index 625172ffc..198fa17af 100644 --- a/tests/gui/interact/state-map-grouping-storage-test.cpp +++ b/tests/gui/interact/state-map-grouping-storage-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file state-map-grouping-storage-test.cpp + ** unit test \ref StateMapGroupingStorage_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/gui/test-gui-test.cpp b/tests/gui/test-gui-test.cpp index a022c7858..1947b2f70 100644 --- a/tests/gui/test-gui-test.cpp +++ b/tests/gui/test-gui-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-gui-test.cpp + ** unit test \ref TestGui_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" @@ -30,9 +34,13 @@ namespace gui { namespace test{ - /**************************************//** - * Hellooooooo the world is just a test - * @test demo of using the test framework + /************************************************************************************//** + * @test demo of writing a unit-test to execute code _implemented within the UI layer_. + * @note the point in question here is the build system and how library dependencies + * are handled. Typically such unit-tests will rather cover framework aspects + * of the UI, not perform a remote controlled execution of the UI. Thus we + * still create a commandline executable, but for this code to work, it + * needs to be _linked against the GUI plugin_ (which is in fact a shared library) */ class TestGui_test : public Test { @@ -45,16 +53,7 @@ namespace test{ - - - /** Register this test class to be invoked in some test groups (suites) - * @remarks this macro \c LUNCHER is defined in run.hpp to simplify - * the registration of test classes. It expands to the - * following static variable definition - * \code - * Launch run_HelloWorld_test("HelloWorld_test","unit common"); - * \endcode - */ + /** Register this test class to be invoked in some test groups */ LAUNCHER (TestGui_test, "unit gui"); diff --git a/tests/include/interface/say_hello.h b/tests/include/interface/say-hello.h similarity index 52% rename from tests/include/interface/say_hello.h rename to tests/include/interface/say-hello.h index 8155879c4..1c0308ee3 100644 --- a/tests/include/interface/say_hello.h +++ b/tests/include/interface/say-hello.h @@ -1,16 +1,22 @@ +/** @file say-hello.h + ** A mock interface to support testing of the interface system + */ + +#ifndef TESTS_INCLUDE_SAY_HELLO_H +#define TESTS_INCLUDE_SAY_HELLO_H + #include "common/interface.h" -/* - one interface which can greet in different languages -*/ +/** mock interface which can greet in different languages */ + LUMIERA_INTERFACE_DECLARE (lumieraorg_testhello, 0, LUMIERA_INTERFACE_SLOT (void, hello, (void)), LUMIERA_INTERFACE_SLOT (void, goodbye, (const char*)), ); -/* - and now one which will be used to test if interfaces can open and call each other -*/ +/** mock interface to test opening and closing of dependent interfaces */ LUMIERA_INTERFACE_DECLARE (lumieraorg_testtest, 0, LUMIERA_INTERFACE_SLOT (void, testit, (void)), ); + +#endif /*TESTS_INCLUDE_SAY_HELLO_H*/ diff --git a/tests/library/advice/advice-basics-test.cpp b/tests/library/advice/advice-basics-test.cpp index e5a65e532..ccb46e2dd 100644 --- a/tests/library/advice/advice-basics-test.cpp +++ b/tests/library/advice/advice-basics-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file advice-basics-test.cpp + ** unit test \ref AdviceBasics_test + */ + #include "lib/test/run.hpp" #include "common/advice.hpp" diff --git a/tests/library/advice/advice-binding-pattern-test.cpp b/tests/library/advice/advice-binding-pattern-test.cpp index c25f7c81a..33a371d7f 100644 --- a/tests/library/advice/advice-binding-pattern-test.cpp +++ b/tests/library/advice/advice-binding-pattern-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file advice-binding-pattern-test.cpp + ** unit test \ref AdviceBindingPattern_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/advice/advice-configuration-test.cpp b/tests/library/advice/advice-configuration-test.cpp index 68a6ff697..496de1df7 100644 --- a/tests/library/advice/advice-configuration-test.cpp +++ b/tests/library/advice/advice-configuration-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file advice-configuration-test.cpp + ** unit test \ref AdviceConfiguration_test + */ + #include "lib/test/run.hpp" //#include "lib/test/test-helper.hpp" diff --git a/tests/library/advice/advice-index-test.cpp b/tests/library/advice/advice-index-test.cpp index 8eaf0bf11..65da2eb9f 100644 --- a/tests/library/advice/advice-index-test.cpp +++ b/tests/library/advice/advice-index-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file advice-index-test.cpp + ** unit test \ref AdviceIndex_test + */ + #include "lib/test/run.hpp" #include "lib/hash-value.h" diff --git a/tests/library/advice/advice-multiplicity-test.cpp b/tests/library/advice/advice-multiplicity-test.cpp index f0641cdb4..a6fd7f8b3 100644 --- a/tests/library/advice/advice-multiplicity-test.cpp +++ b/tests/library/advice/advice-multiplicity-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file advice-multiplicity-test.cpp + ** unit test \ref AdviceMultiplicity_test + */ + #include "lib/test/run.hpp" //#include "lib/test/test-helper.hpp" diff --git a/tests/library/advice/advice-situations-test.cpp b/tests/library/advice/advice-situations-test.cpp index 292df259a..7b5c3236e 100644 --- a/tests/library/advice/advice-situations-test.cpp +++ b/tests/library/advice/advice-situations-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file advice-situations-test.cpp + ** unit test \ref AdviceSituations_test + */ + #include "lib/test/run.hpp" //#include "lib/test/test-helper.hpp" diff --git a/tests/library/allocation-cluster-test.cpp b/tests/library/allocation-cluster-test.cpp index 20bab9bbd..7fdec0f04 100644 --- a/tests/library/allocation-cluster-test.cpp +++ b/tests/library/allocation-cluster-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file allocation-cluster-test.cpp + ** unit test \ref AllocationCluster_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/app-config-test.cpp b/tests/library/app-config-test.cpp index 5361abb40..6f4c78b02 100644 --- a/tests/library/app-config-test.cpp +++ b/tests/library/app-config-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file app-config-test.cpp + ** unit test \ref Appconfig_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/bool-checkable-test.cpp b/tests/library/bool-checkable-test.cpp index c4f51b83a..ae1a3c1c8 100644 --- a/tests/library/bool-checkable-test.cpp +++ b/tests/library/bool-checkable-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file bool-checkable-test.cpp + ** unit test \ref BoolCheckable_test + */ + #include "lib/test/run.hpp" #include "lib/bool-checkable.hpp" diff --git a/tests/library/c-lib/test-errorstate.c b/tests/library/c-lib/test-errorstate.c index b936c1d30..16e83af11 100644 --- a/tests/library/c-lib/test-errorstate.c +++ b/tests/library/c-lib/test-errorstate.c @@ -20,6 +20,12 @@ * *****************************************************/ +/** @file test-errorstate.c + ** C unit test to cover basic error handling in C code + ** We manage an _errorstate variable_ in thread local storage, + ** which allows to set an global error state per thread. + */ + #include #include diff --git a/tests/library/c-lib/test-llist.c b/tests/library/c-lib/test-llist.c index 85162e608..e97af241f 100644 --- a/tests/library/c-lib/test-llist.c +++ b/tests/library/c-lib/test-llist.c @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-llist.c + ** C unit test to cover a linked list library implementation + ** @see llist.h + */ + #include diff --git a/tests/library/c-lib/test-locking.c b/tests/library/c-lib/test-locking.c index c883dc2ff..7703a6a8f 100644 --- a/tests/library/c-lib/test-locking.c +++ b/tests/library/c-lib/test-locking.c @@ -20,6 +20,14 @@ * *****************************************************/ +/** @file test-locking.c + ** C unit test to cover convenience setup for POSIX locking primitives + ** These convenience macros are intended for use in low-level C code, + ** where minimal and precise locking is relevant for performance reasons. + ** @see mutex.h + ** @see condition.h + */ + #include "lib/test/test.h" #include "lib/mutex.h" diff --git a/tests/library/c-lib/test-luid.c b/tests/library/c-lib/test-luid.c index f2902c74b..d49ebc68c 100644 --- a/tests/library/c-lib/test-luid.c +++ b/tests/library/c-lib/test-luid.c @@ -20,6 +20,12 @@ * *****************************************************/ +/** @file test-luid.c + ** C unit test to cover generation of Lumiera Uniform Identifier hashes + ** @see luid.h + ** @see hash-indexed.hpp + */ + #include "lib/luid.h" diff --git a/tests/library/c-lib/test-mpool.c b/tests/library/c-lib/test-mpool.c index 5667a2506..231c16955 100644 --- a/tests/library/c-lib/test-mpool.c +++ b/tests/library/c-lib/test-mpool.c @@ -20,6 +20,13 @@ * *****************************************************/ +/** @file test-mpool.c + ** C unit test to cover a memory pool custom allocator + ** + ** @warning unfinished implementation as of 2016 + ** @see mpool.h + */ + #include "lib/test/test.h" #include "lib/mpool.h" diff --git a/tests/library/c-lib/test-priqueue.c b/tests/library/c-lib/test-priqueue.c index bc6459c15..ff3c86510 100644 --- a/tests/library/c-lib/test-priqueue.c +++ b/tests/library/c-lib/test-priqueue.c @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-priqueue.c + ** C unit test to cover a priority queue library implementation + ** @see priqueue.h + */ + #include "lib/test/test.h" #include "lib/priqueue.h" diff --git a/tests/library/c-lib/test-psplay.c b/tests/library/c-lib/test-psplay.c index dc50bb548..fd9760f6b 100644 --- a/tests/library/c-lib/test-psplay.c +++ b/tests/library/c-lib/test-psplay.c @@ -20,6 +20,13 @@ * *****************************************************/ +/** @file test-psplay.c + ** C unit test to cover a probabilistic splay tree library implementation. + ** These tree data structures are used as key-value store in several of the + ** management facilities of the backend + ** @see psplay.h + */ + #include #include diff --git a/tests/library/c-lib/test-safeclib.c b/tests/library/c-lib/test-safeclib.c index 63e503b4a..c0f80d10f 100644 --- a/tests/library/c-lib/test-safeclib.c +++ b/tests/library/c-lib/test-safeclib.c @@ -20,6 +20,11 @@ * *****************************************************/ +/** @file test-safeclib.c + ** C unit test to cover size checked C operations + ** @see safeclib.h + */ + #include "lib/safeclib.h" #include "lib/tmpbuf.h" /* not factored out yet */ diff --git a/tests/library/c-lib/test-slist.c b/tests/library/c-lib/test-slist.c index b18374194..4d34f9fd4 100644 --- a/tests/library/c-lib/test-slist.c +++ b/tests/library/c-lib/test-slist.c @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-slist.c + ** C unit test to cover a single linked list library implementation + */ + #include "lib/slist.h" #include "lib/test/test.h" diff --git a/tests/library/c-lib/test-time.c b/tests/library/c-lib/test-time.c index 67c42c133..09f3e4589 100644 --- a/tests/library/c-lib/test-time.c +++ b/tests/library/c-lib/test-time.c @@ -20,6 +20,13 @@ * *****************************************************/ +/** @file test-time.c + ** C unit test to cover the basic low-level time handling operations + ** @see time.h + ** @see timevalue.hpp + ** @see TimeValue_test high-level time entities + */ + #include "lib/test/test.h" #include "lib/time.h" diff --git a/tests/library/cmdline-wrapper-test.cpp b/tests/library/cmdline-wrapper-test.cpp index 0bbecf71d..0796f4518 100644 --- a/tests/library/cmdline-wrapper-test.cpp +++ b/tests/library/cmdline-wrapper-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file cmdline-wrapper-test.cpp + ** unit test \ref CmdlineWrapper_test + */ + #include "lib/test/run.hpp" #include "lib/cmdline.hpp" diff --git a/tests/library/custom-shared-ptr-test.cpp b/tests/library/custom-shared-ptr-test.cpp index 189210fab..53d68ebf7 100644 --- a/tests/library/custom-shared-ptr-test.cpp +++ b/tests/library/custom-shared-ptr-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file custom-shared-ptr-test.cpp + ** unit test \ref CustomSharedPtr_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/del-stash-test.cpp b/tests/library/del-stash-test.cpp index e35140eb0..a50f545c4 100644 --- a/tests/library/del-stash-test.cpp +++ b/tests/library/del-stash-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file del-stash-test.cpp + ** unit test \ref DelStash_test + */ + #include "lib/test/run.hpp" #include "lib/del-stash.hpp" diff --git a/tests/library/dependency-factory-test.cpp b/tests/library/dependency-factory-test.cpp index 95ed39890..7dca01d61 100644 --- a/tests/library/dependency-factory-test.cpp +++ b/tests/library/dependency-factory-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file dependency-factory-test.cpp + ** unit test \ref DependencyFactory_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/diff/diff-complex-application-test.cpp b/tests/library/diff/diff-complex-application-test.cpp index 095d7cfa6..5b4fff122 100644 --- a/tests/library/diff/diff-complex-application-test.cpp +++ b/tests/library/diff/diff-complex-application-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file diff-complex-application-test.cpp + ** unit test \ref DiffComplexApplication_test + */ + #include "lib/test/run.hpp" #include "lib/format-util.hpp" diff --git a/tests/library/diff/diff-index-table-test.cpp b/tests/library/diff/diff-index-table-test.cpp index 36ca475cb..ad9a8946c 100644 --- a/tests/library/diff/diff-index-table-test.cpp +++ b/tests/library/diff/diff-index-table-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file diff-index-table-test.cpp + ** unit test \ref DiffIndexTable_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/diff/diff-list-application-test.cpp b/tests/library/diff/diff-list-application-test.cpp index f8bf3639c..30f0348e7 100644 --- a/tests/library/diff/diff-list-application-test.cpp +++ b/tests/library/diff/diff-list-application-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file diff-list-application-test.cpp + ** unit test \ref DiffListApplication_test + */ + #include "lib/test/run.hpp" #include "lib/diff/list-diff-application.hpp" diff --git a/tests/library/diff/diff-list-generation-test.cpp b/tests/library/diff/diff-list-generation-test.cpp index 26add3b3b..794f46c1f 100644 --- a/tests/library/diff/diff-list-generation-test.cpp +++ b/tests/library/diff/diff-list-generation-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file diff-list-generation-test.cpp + ** unit test \ref DiffListGeneration_test + */ + #include "lib/test/run.hpp" #include "lib/diff/list-diff-detector.hpp" diff --git a/tests/library/diff/diff-tree-application-test.cpp b/tests/library/diff/diff-tree-application-test.cpp index 439bd2c39..9f16b3dea 100644 --- a/tests/library/diff/diff-tree-application-test.cpp +++ b/tests/library/diff/diff-tree-application-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file diff-tree-application-test.cpp + ** unit test \ref DiffTreeApplication_test + */ + #include "lib/test/run.hpp" #include "lib/format-util.hpp" diff --git a/tests/library/diff/gen-node-basic-test.cpp b/tests/library/diff/gen-node-basic-test.cpp index 31d569756..0608db467 100644 --- a/tests/library/diff/gen-node-basic-test.cpp +++ b/tests/library/diff/gen-node-basic-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file gen-node-basic-test.cpp + ** unit test \ref GenNodeBasic_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/diff/generic-record-representation-test.cpp b/tests/library/diff/generic-record-representation-test.cpp index 82a7e6ddb..1bd5c6328 100644 --- a/tests/library/diff/generic-record-representation-test.cpp +++ b/tests/library/diff/generic-record-representation-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file generic-record-representation-test.cpp + ** unit test \ref GenericRecordRepresentation_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/diff/tree-mutator-binding-test.cpp b/tests/library/diff/tree-mutator-binding-test.cpp index 0e680ac3a..56df7c00e 100644 --- a/tests/library/diff/tree-mutator-binding-test.cpp +++ b/tests/library/diff/tree-mutator-binding-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file tree-mutator-binding-test.cpp + ** unit test \ref TreeMutatorBinding_test + */ + #include "lib/test/run.hpp" #include "lib/format-util.hpp" diff --git a/tests/library/diff/tree-mutator-test.cpp b/tests/library/diff/tree-mutator-test.cpp index 34ceb4b87..a6ca65d11 100644 --- a/tests/library/diff/tree-mutator-test.cpp +++ b/tests/library/diff/tree-mutator-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file tree-mutator-test.cpp + ** unit test \ref TreeMutator_test + */ + #include "lib/test/run.hpp" #include "lib/format-util.hpp" diff --git a/tests/library/exceptionerrortest.cpp b/tests/library/exception-error-test.cpp similarity index 99% rename from tests/library/exceptionerrortest.cpp rename to tests/library/exception-error-test.cpp index f19259b99..d057f2578 100644 --- a/tests/library/exceptionerrortest.cpp +++ b/tests/library/exception-error-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file exceptionerrortest.cpp + ** unit test \ref ExceptionError_test + */ + #include "lib/error.h" diff --git a/tests/library/format-cout-test.cpp b/tests/library/format-cout-test.cpp index edfb86acf..fb17e1648 100644 --- a/tests/library/format-cout-test.cpp +++ b/tests/library/format-cout-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file format-cout-test.cpp + ** unit test \ref FormatCOUT_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/format-helper-test.cpp b/tests/library/format-helper-test.cpp index 753baebcb..eb1c46f5e 100644 --- a/tests/library/format-helper-test.cpp +++ b/tests/library/format-helper-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file format-helper-test.cpp + ** unit test \ref FormatHelper_test + */ + #include "lib/test/run.hpp" #include "lib/format-util.hpp" diff --git a/tests/library/format-string-test.cpp b/tests/library/format-string-test.cpp index 74408cddc..094a9de03 100644 --- a/tests/library/format-string-test.cpp +++ b/tests/library/format-string-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file format-string-test.cpp + ** unit test \ref FormatString_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/functor-util-test.cpp b/tests/library/functor-util-test.cpp index f1f9446e9..da5a29f3c 100644 --- a/tests/library/functor-util-test.cpp +++ b/tests/library/functor-util-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file functor-util-test.cpp + ** unit test \ref FunctorUtil_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/hash-generator-test.cpp b/tests/library/hash-generator-test.cpp index 4a494c094..4bcbebed1 100644 --- a/tests/library/hash-generator-test.cpp +++ b/tests/library/hash-generator-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file hash-generator-test.cpp + ** unit test \ref HashGenerator_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/library/hash-indexed-test.cpp b/tests/library/hash-indexed-test.cpp index f709389a4..ad84be5fe 100644 --- a/tests/library/hash-indexed-test.cpp +++ b/tests/library/hash-indexed-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file hash-indexed-test.cpp + ** unit test \ref HashIndexed_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/hash-standard-to-boost-bridge-test.cpp b/tests/library/hash-standard-to-boost-bridge-test.cpp index ff1cf2a08..27325e9d1 100644 --- a/tests/library/hash-standard-to-boost-bridge-test.cpp +++ b/tests/library/hash-standard-to-boost-bridge-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file hash-standard-to-boost-bridge-test.cpp + ** unit test \ref HashStandardToBoostBridge_test + */ + #include "lib/test/run.hpp" #include "lib/hash-standard.hpp" diff --git a/tests/library/helloworldtest.cpp b/tests/library/helloworldtest.cpp index e61e948c4..f0993fc78 100644 --- a/tests/library/helloworldtest.cpp +++ b/tests/library/helloworldtest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file helloworldtest.cpp + ** unit test \ref HelloWorld_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/library/hierarchy-orientation-indicator-test.cpp b/tests/library/hierarchy-orientation-indicator-test.cpp index 76cae0cac..b3a375b7a 100644 --- a/tests/library/hierarchy-orientation-indicator-test.cpp +++ b/tests/library/hierarchy-orientation-indicator-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file hierarchy-orientation-indicator-test.cpp + ** unit test \ref HierarchyOrientationIndicator_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/idi/generic-id-function-test.cpp b/tests/library/idi/generic-id-function-test.cpp index 78537764d..6951cddaf 100644 --- a/tests/library/idi/generic-id-function-test.cpp +++ b/tests/library/idi/generic-id-function-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file generic-id-function-test.cpp + ** unit test \ref GenericIdFunction_test + */ + #include "lib/test/run.hpp" //#include "lib/test/test-helper.hpp" diff --git a/tests/library/item-wrapper-test.cpp b/tests/library/item-wrapper-test.cpp index 44f707e1f..c8d585635 100644 --- a/tests/library/item-wrapper-test.cpp +++ b/tests/library/item-wrapper-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file item-wrapper-test.cpp + ** unit test \ref ItemWrapper_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-adapter-stl-test.cpp b/tests/library/iter-adapter-stl-test.cpp index 9ee927efa..f4783da82 100644 --- a/tests/library/iter-adapter-stl-test.cpp +++ b/tests/library/iter-adapter-stl-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-adapter-stl-test.cpp + ** unit test \ref IterAdapterSTL_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-adapter-test.cpp b/tests/library/iter-adapter-test.cpp index b5aaea55f..b60f268cc 100644 --- a/tests/library/iter-adapter-test.cpp +++ b/tests/library/iter-adapter-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-adapter-test.cpp + ** unit test \ref IterAdapter_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-cursor-test.cpp b/tests/library/iter-cursor-test.cpp index 28f3e5b85..64a1604b7 100644 --- a/tests/library/iter-cursor-test.cpp +++ b/tests/library/iter-cursor-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-cursor-test.cpp + ** unit test \ref IterCursor_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-explorer-test.cpp b/tests/library/iter-explorer-test.cpp index f22981e8d..ad7673a8b 100644 --- a/tests/library/iter-explorer-test.cpp +++ b/tests/library/iter-explorer-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-explorer-test.cpp + ** unit test \ref IterExplorer_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-queue-test.cpp b/tests/library/iter-queue-test.cpp index b0a09a091..1000fe573 100644 --- a/tests/library/iter-queue-test.cpp +++ b/tests/library/iter-queue-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-queue-test.cpp + ** unit test \ref IterQueue_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-source-test.cpp b/tests/library/iter-source-test.cpp index 5993b2501..a5740a199 100644 --- a/tests/library/iter-source-test.cpp +++ b/tests/library/iter-source-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-source-test.cpp + ** unit test \ref IterSource_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/iter-stack-test.cpp b/tests/library/iter-stack-test.cpp index 5a35e4280..3be69c5c8 100644 --- a/tests/library/iter-stack-test.cpp +++ b/tests/library/iter-stack-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iter-stack-test.cpp + ** unit test \ref IterStack_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/itertools-test.cpp b/tests/library/itertools-test.cpp index 04b1ba088..ca7fddc1e 100644 --- a/tests/library/itertools-test.cpp +++ b/tests/library/itertools-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file itertools-test.cpp + ** unit test \ref IterTools_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/lifecycletest.cpp b/tests/library/life-cycle-test.cpp similarity index 97% rename from tests/library/lifecycletest.cpp rename to tests/library/life-cycle-test.cpp index c437aa74b..573a8be03 100644 --- a/tests/library/lifecycletest.cpp +++ b/tests/library/life-cycle-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file lifecycletest.cpp + ** unit test \ref LifeCycle_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/linked-elements-test.cpp b/tests/library/linked-elements-test.cpp index 102e97eec..2a9101528 100644 --- a/tests/library/linked-elements-test.cpp +++ b/tests/library/linked-elements-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file linked-elements-test.cpp + ** unit test \ref LinkedElements_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/maybe-value-test.cpp b/tests/library/maybe-value-test.cpp index b739a68b9..a5630af9d 100644 --- a/tests/library/maybe-value-test.cpp +++ b/tests/library/maybe-value-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file maybe-value-test.cpp + ** unit test \ref MaybeValue_test + */ + diff --git a/tests/library/meta/access-casted-test.cpp b/tests/library/meta/access-casted-test.cpp index f0332b78e..e6ad2f55a 100644 --- a/tests/library/meta/access-casted-test.cpp +++ b/tests/library/meta/access-casted-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file access-casted-test.cpp + ** unit test \ref AccessCasted_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/meta/duck-detector-test.cpp b/tests/library/meta/duck-detector-test.cpp index 78a4c5469..fe14f1be0 100644 --- a/tests/library/meta/duck-detector-test.cpp +++ b/tests/library/meta/duck-detector-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file duck-detector-test.cpp + ** unit test \ref DuckDetector_test + */ + #include "lib/test/run.hpp" #include "lib/meta/duck-detector.hpp" diff --git a/tests/library/meta/dummy-functions.hpp b/tests/library/meta/dummy-functions.hpp index 2114ee6a9..0b776236e 100644 --- a/tests/library/meta/dummy-functions.hpp +++ b/tests/library/meta/dummy-functions.hpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file dummy-functions.hpp + ** dummy functions to support unit testing of function metaprogramming helpers + */ + #ifndef LIB_META_DUMMY_FUNCTIONS_H #define LIB_META_DUMMY_FUNCTIONS_H diff --git a/tests/library/meta/function-composition-test.cpp b/tests/library/meta/function-composition-test.cpp index 71a8172a0..a807b3f1e 100644 --- a/tests/library/meta/function-composition-test.cpp +++ b/tests/library/meta/function-composition-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file function-composition-test.cpp + ** unit test \ref FunctionComposition_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/meta/function-erasure-test.cpp b/tests/library/meta/function-erasure-test.cpp index 11824da8e..bb66d91b5 100644 --- a/tests/library/meta/function-erasure-test.cpp +++ b/tests/library/meta/function-erasure-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file function-erasure-test.cpp + ** unit test \ref FunctionErasure_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/meta/generator-combinations-test.cpp b/tests/library/meta/generator-combinations-test.cpp index e63665502..8ce8b7f43 100644 --- a/tests/library/meta/generator-combinations-test.cpp +++ b/tests/library/meta/generator-combinations-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file generator-combinations-test.cpp + ** unit test \ref GeneratorCombinations_test + */ + #include "lib/test/run.hpp" #include "lib/meta/generator.hpp" diff --git a/tests/library/meta/iterable-classification-test.cpp b/tests/library/meta/iterable-classification-test.cpp index 8f0c5f4d4..3c5e0b3c0 100644 --- a/tests/library/meta/iterable-classification-test.cpp +++ b/tests/library/meta/iterable-classification-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file iterable-classification-test.cpp + ** unit test \ref IterableClassification_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/meta/meta-utils-test.cpp b/tests/library/meta/meta-utils-test.cpp index e71123f61..db14c6d00 100644 --- a/tests/library/meta/meta-utils-test.cpp +++ b/tests/library/meta/meta-utils-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file meta-utils-test.cpp + ** unit test \ref MetaUtils_test + */ + #include "lib/test/run.hpp" #include "lib/meta/util.hpp" diff --git a/tests/library/meta/tuple-record-init-test.cpp b/tests/library/meta/tuple-record-init-test.cpp index c9c305088..65c73a50f 100644 --- a/tests/library/meta/tuple-record-init-test.cpp +++ b/tests/library/meta/tuple-record-init-test.cpp @@ -19,6 +19,10 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. * *****************************************************/ + +/** @file tuple-record-init-test.cpp + ** unit test \ref TupleRecordInit_test + */ ///@file diff --git a/tests/library/meta/type-demangling-test.cpp b/tests/library/meta/type-demangling-test.cpp index 8928fb3a3..3257b0900 100644 --- a/tests/library/meta/type-demangling-test.cpp +++ b/tests/library/meta/type-demangling-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file type-demangling-test.cpp + ** unit test \ref TypeDemangling_test + */ + #include "lib/test/run.hpp" #include "lib/meta/util.hpp" diff --git a/tests/library/meta/type-display-test.cpp b/tests/library/meta/type-display-test.cpp index 7fef2e56c..ca201c475 100644 --- a/tests/library/meta/type-display-test.cpp +++ b/tests/library/meta/type-display-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file type-display-test.cpp + ** unit test \ref TypeDisplay_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/meta/typelist-test.cpp b/tests/library/meta/typelist-test.cpp index a1f9ede6f..404ad1d19 100644 --- a/tests/library/meta/typelist-test.cpp +++ b/tests/library/meta/typelist-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file typelist-test.cpp + ** unit test \ref TypeList_test + */ + #include "lib/test/run.hpp" #include "lib/meta/typelist.hpp" diff --git a/tests/library/meta/typelist-util-test.cpp b/tests/library/meta/typelist-util-test.cpp index 55de3474b..c7b2fee47 100644 --- a/tests/library/meta/typelist-util-test.cpp +++ b/tests/library/meta/typelist-util-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file typelist-util-test.cpp + ** unit test \ref TypeListUtil_test + */ + #include "lib/test/run.hpp" #include "lib/meta/typelist-util.hpp" diff --git a/tests/library/meta/virtual-copy-support-test.cpp b/tests/library/meta/virtual-copy-support-test.cpp index eda331d68..544020262 100644 --- a/tests/library/meta/virtual-copy-support-test.cpp +++ b/tests/library/meta/virtual-copy-support-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file virtual-copy-support-test.cpp + ** unit test \ref VirtualCopySupport_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/multifact-argument-test.cpp b/tests/library/multifact-argument-test.cpp index 47fadd37a..0983feacb 100644 --- a/tests/library/multifact-argument-test.cpp +++ b/tests/library/multifact-argument-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file multifact-argument-test.cpp + ** unit test \ref MultiFactArgument_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/multifact-singleton-test.cpp b/tests/library/multifact-singleton-test.cpp index 6153c7217..bf087ab23 100644 --- a/tests/library/multifact-singleton-test.cpp +++ b/tests/library/multifact-singleton-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file multifact-singleton-test.cpp + ** unit test \ref MultiFactSingleton_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/multifact-test.cpp b/tests/library/multifact-test.cpp index 55e0e84fd..b716c0878 100644 --- a/tests/library/multifact-test.cpp +++ b/tests/library/multifact-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file multifact-test.cpp + ** unit test \ref MultiFact_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/null-value-test.cpp b/tests/library/null-value-test.cpp index af67e8ba9..31f387f7b 100644 --- a/tests/library/null-value-test.cpp +++ b/tests/library/null-value-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file null-value-test.cpp + ** unit test \ref NullValue_test + */ + diff --git a/tests/library/opaque-holder-test.cpp b/tests/library/opaque-holder-test.cpp index da866abf2..cc8a8a371 100644 --- a/tests/library/opaque-holder-test.cpp +++ b/tests/library/opaque-holder-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file opaque-holder-test.cpp + ** unit test \ref OpaqueHolder_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/opaque-unchecked-buffer-test.cpp b/tests/library/opaque-unchecked-buffer-test.cpp index cdf8d7725..35f0f8303 100644 --- a/tests/library/opaque-unchecked-buffer-test.cpp +++ b/tests/library/opaque-unchecked-buffer-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file opaque-unchecked-buffer-test.cpp + ** unit test \ref OpaqueUncheckedBuffer_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/optional-ref-test.cpp b/tests/library/optional-ref-test.cpp index c061fb686..fa6648e2f 100644 --- a/tests/library/optional-ref-test.cpp +++ b/tests/library/optional-ref-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file optional-ref-test.cpp + ** unit test \ref OptionalRef_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/polymorphic-value-test.cpp b/tests/library/polymorphic-value-test.cpp index 785838ffe..528fdeea1 100644 --- a/tests/library/polymorphic-value-test.cpp +++ b/tests/library/polymorphic-value-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file polymorphic-value-test.cpp + ** unit test \ref PolymorphicValue_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/query-text-test.cpp b/tests/library/query-text-test.cpp index d9fb8d19b..a3af0ed71 100644 --- a/tests/library/query-text-test.cpp +++ b/tests/library/query-text-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file query-text-test.cpp + ** unit test \ref QueryText_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/query/query-utils-test.cpp b/tests/library/query/query-utils-test.cpp index 4e2b3eae6..c513b2e5e 100644 --- a/tests/library/query/query-utils-test.cpp +++ b/tests/library/query/query-utils-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file query-utils-test.cpp + ** unit test \ref QueryUtils_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/library/ref-array-test.cpp b/tests/library/ref-array-test.cpp index 52734cd60..bd98dbcff 100644 --- a/tests/library/ref-array-test.cpp +++ b/tests/library/ref-array-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file ref-array-test.cpp + ** unit test \ref RefArray_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/library/removefromsettest.cpp b/tests/library/removefromsettest.cpp index fe4b14729..7044ce3ad 100644 --- a/tests/library/removefromsettest.cpp +++ b/tests/library/removefromsettest.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file removefromsettest.cpp + ** unit test \ref RemoveFromSet_test + */ + #include "lib/test/run.hpp" #include "lib/util-foreach.hpp" diff --git a/tests/library/sanitised-identifier-test.cpp b/tests/library/sanitised-identifier-test.cpp index a0b0d59de..7d7ce6d18 100644 --- a/tests/library/sanitised-identifier-test.cpp +++ b/tests/library/sanitised-identifier-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sanitised-identifier-test.cpp + ** unit test \ref SanitizedIdentifier_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/library/scoped-collection-test.cpp b/tests/library/scoped-collection-test.cpp index 1c194b96c..0e1c5e707 100644 --- a/tests/library/scoped-collection-test.cpp +++ b/tests/library/scoped-collection-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scoped-collection-test.cpp + ** unit test \ref ScopedCollection_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/scoped-holder-test.cpp b/tests/library/scoped-holder-test.cpp index ec921efc7..c8549a6be 100644 --- a/tests/library/scoped-holder-test.cpp +++ b/tests/library/scoped-holder-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scoped-holder-test.cpp + ** unit test \ref ScopedHolder_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/scoped-holder-transfer-test.cpp b/tests/library/scoped-holder-transfer-test.cpp index f7c9a2e22..d6b9abe60 100644 --- a/tests/library/scoped-holder-transfer-test.cpp +++ b/tests/library/scoped-holder-transfer-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scoped-holder-transfer-test.cpp + ** unit test \ref ScopedHolderTransfer_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/scoped-ptrvect-test.cpp b/tests/library/scoped-ptrvect-test.cpp index 98b197485..004a6d754 100644 --- a/tests/library/scoped-ptrvect-test.cpp +++ b/tests/library/scoped-ptrvect-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file scoped-ptrvect-test.cpp + ** unit test \ref ScopedPtrVect_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/search-path-splitter-test.cpp b/tests/library/search-path-splitter-test.cpp index 5f9cd6d4b..4dedad651 100644 --- a/tests/library/search-path-splitter-test.cpp +++ b/tests/library/search-path-splitter-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file search-path-splitter-test.cpp + ** unit test \ref SearchPathSplitter_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/simple-allocator-test.cpp b/tests/library/simple-allocator-test.cpp index 2982e44e3..d876a2947 100644 --- a/tests/library/simple-allocator-test.cpp +++ b/tests/library/simple-allocator-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file simple-allocator-test.cpp + ** unit test \ref SimpleAllocator_test + */ + #include "lib/test/run.hpp" #include "lib/simple-allocator.hpp" diff --git a/tests/library/singleton-subclass-test.cpp b/tests/library/singleton-subclass-test.cpp index 0fa36c40a..521189a35 100644 --- a/tests/library/singleton-subclass-test.cpp +++ b/tests/library/singleton-subclass-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file singleton-subclass-test.cpp + ** unit test \ref SingletonSubclass_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/singleton-test.cpp b/tests/library/singleton-test.cpp index dfe5c4998..1fd565fb4 100644 --- a/tests/library/singleton-test.cpp +++ b/tests/library/singleton-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file singleton-test.cpp + ** unit test \ref Singleton_test + */ + #include "lib/test/run.hpp" #include "lib/format-string.hpp" diff --git a/tests/library/singleton-testmock-test.cpp b/tests/library/singleton-testmock-test.cpp index a9ecc51f1..8749b7957 100644 --- a/tests/library/singleton-testmock-test.cpp +++ b/tests/library/singleton-testmock-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file singleton-testmock-test.cpp + ** unit test \ref SingletonTestMock_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/sub-id-test.cpp b/tests/library/sub-id-test.cpp index fb420c946..a29a953de 100644 --- a/tests/library/sub-id-test.cpp +++ b/tests/library/sub-id-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file sub-id-test.cpp + ** unit test \ref SubID_test + */ + #include "lib/test/run.hpp" #include "lib/util.hpp" diff --git a/tests/library/symbol-hashtable-test.cpp b/tests/library/symbol-hashtable-test.cpp index ec5e8b108..6a6088673 100644 --- a/tests/library/symbol-hashtable-test.cpp +++ b/tests/library/symbol-hashtable-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file symbol-hashtable-test.cpp + ** unit test \ref SymbolHashtable_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/symbol-test.cpp b/tests/library/symbol-test.cpp index 62bbb1ea6..c0f4168aa 100644 --- a/tests/library/symbol-test.cpp +++ b/tests/library/symbol-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file symbol-test.cpp + ** unit test \ref Symbol_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/test-target-obj.hpp b/tests/library/test-target-obj.hpp index 0f6279b3e..d09b5a598 100644 --- a/tests/library/test-target-obj.hpp +++ b/tests/library/test-target-obj.hpp @@ -20,6 +20,12 @@ */ +/** @file test-target-obj.hpp + ** Dummy target object to be created by factory for unit tests + ** Used to verify sane memory management and instance lifecycle for such + ** objects generated as singleton or by factory + */ + #ifndef LIBRARY_TEST_TARGET_OBJ_H #define LIBRARY_TEST_TARGET_OBJ_H diff --git a/tests/library/test/test-event-log-test.cpp b/tests/library/test/test-event-log-test.cpp index 5c60f9a0c..18ac7c2ac 100644 --- a/tests/library/test/test-event-log-test.cpp +++ b/tests/library/test/test-event-log-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-event-log-test.cpp + ** unit test \ref TestEventLog_test + */ + #include "lib/test/run.hpp" #include "lib/format-util.hpp" diff --git a/tests/library/test/test-helper-test.cpp b/tests/library/test/test-helper-test.cpp index a01bfc47f..a9335a02a 100644 --- a/tests/library/test/test-helper-test.cpp +++ b/tests/library/test/test-helper-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-helper-test.cpp + ** unit test \ref TestHelper_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/test/test-helper-variadic-test.cpp b/tests/library/test/test-helper-variadic-test.cpp index 99474557b..8f7606cf9 100644 --- a/tests/library/test/test-helper-variadic-test.cpp +++ b/tests/library/test/test-helper-variadic-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-helper-variadic-test.cpp + ** unit test \ref TestHelperVariadic_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/test/test-option-test.cpp b/tests/library/test/test-option-test.cpp index b1fdc2032..dfb47bfeb 100644 --- a/tests/library/test/test-option-test.cpp +++ b/tests/library/test/test-option-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file test-option-test.cpp + ** unit test \ref TestOption_test + */ + #include "lib/test/run.hpp" #include "lib/test/testoption.hpp" diff --git a/tests/library/typed-allocation-manager-test.cpp b/tests/library/typed-allocation-manager-test.cpp index 4d6616a8f..90fe1c444 100644 --- a/tests/library/typed-allocation-manager-test.cpp +++ b/tests/library/typed-allocation-manager-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file typed-allocation-manager-test.cpp + ** unit test \ref TypedAllocationManager_test + */ + #include "lib/test/run.hpp" #include "lib/typed-allocation-manager.hpp" diff --git a/tests/library/unique-malloc-owner-test.cpp b/tests/library/unique-malloc-owner-test.cpp index 199ae20cf..11c500456 100644 --- a/tests/library/unique-malloc-owner-test.cpp +++ b/tests/library/unique-malloc-owner-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file unique-malloc-owner-test.cpp + ** unit test \ref UniqueMallocOwner_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/util-collection-test.cpp b/tests/library/util-collection-test.cpp index 65e773715..eb6292598 100644 --- a/tests/library/util-collection-test.cpp +++ b/tests/library/util-collection-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file util-collection-test.cpp + ** unit test \ref UtilCollection_test + */ + #include "lib/test/run.hpp" #include "lib/itertools.hpp" diff --git a/tests/library/util-floordiv-test.cpp b/tests/library/util-floordiv-test.cpp index 0ee9d4788..766e41b41 100644 --- a/tests/library/util-floordiv-test.cpp +++ b/tests/library/util-floordiv-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file util-floordiv-test.cpp + ** unit test \ref UtilFloordiv_test + */ + #include "lib/test/run.hpp" #include "lib/util-quant.hpp" diff --git a/tests/library/util-floorwrap-test.cpp b/tests/library/util-floorwrap-test.cpp index e0eee28f1..b4a23e83c 100644 --- a/tests/library/util-floorwrap-test.cpp +++ b/tests/library/util-floorwrap-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file util-floorwrap-test.cpp + ** unit test \ref UtilFloorwrap_test + */ + #include "lib/test/run.hpp" #include "lib/test/test-helper.hpp" diff --git a/tests/library/util-foreach-test.cpp b/tests/library/util-foreach-test.cpp index 5993ca209..5be9fc175 100644 --- a/tests/library/util-foreach-test.cpp +++ b/tests/library/util-foreach-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file util-foreach-test.cpp + ** unit test \ref UtilForeach_test + */ + #include "lib/test/run.hpp" #include "lib/util-foreach.hpp" diff --git a/tests/library/variant-test.cpp b/tests/library/variant-test.cpp index 3532919c1..7340efc67 100644 --- a/tests/library/variant-test.cpp +++ b/tests/library/variant-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file variant-test.cpp + ** unit test \ref Variant_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/vector-transfer-test.cpp b/tests/library/vector-transfer-test.cpp index 143594342..d46dc81fe 100644 --- a/tests/library/vector-transfer-test.cpp +++ b/tests/library/vector-transfer-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file vector-transfer-test.cpp + ** unit test \ref VectorTransfer_test + */ + #include "lib/test/run.hpp" diff --git a/tests/library/verb-function-dispatch-test.cpp b/tests/library/verb-function-dispatch-test.cpp index 5171154cd..bed17b0ad 100644 --- a/tests/library/verb-function-dispatch-test.cpp +++ b/tests/library/verb-function-dispatch-test.cpp @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file verb-function-dispatch-test.cpp + ** unit test \ref VerbFunctionDispatch_test + */ + #include "lib/test/run.hpp" #include "lib/verb-token.hpp" diff --git a/tests/operation/bugs/hello-bug-test.cpp b/tests/operation/bugs/hello-bug-test.cpp index 34f7e45fb..a637143ce 100644 --- a/tests/operation/bugs/hello-bug-test.cpp +++ b/tests/operation/bugs/hello-bug-test.cpp @@ -1,5 +1,5 @@ /* - HelloBug(test) - placeholder for running bug regression tests + HelloBug(Test) - placeholder for running bug regression tests Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -20,6 +20,10 @@ * *****************************************************/ +/** @file hello-bug-test.cpp + ** unit test \ref HelloBug_test + */ + #include "lib/test/run.hpp" diff --git a/tests/plugin/test-c-plugin/example_plugin.c b/tests/plugin/test-c-plugin/example-plugin.c similarity index 96% rename from tests/plugin/test-c-plugin/example_plugin.c rename to tests/plugin/test-c-plugin/example-plugin.c index 2ac408a7a..438f75f50 100644 --- a/tests/plugin/test-c-plugin/example_plugin.c +++ b/tests/plugin/test-c-plugin/example-plugin.c @@ -1,5 +1,5 @@ /* - example_plugin - example plugin for testing the interface/plugin system + ExamplePlugin - example plugin for testing the interface/plugin system Copyright (C) Lumiera.org 2008, Christian Thaeter @@ -20,13 +20,20 @@ * *****************************************************/ +/** @file example-plugin.c + ** Dummy C plug-in to cover the plugin loader for unit test + ** This file defines a Lumiera plug-in written in plain C, + ** implementing the `lumieraorg_testhello` interface + ** @see test-interfaces.c + */ + #include #include "common/interface-descriptor.h" #include "common/config-interface.h" -#include "interface/say_hello.h" +#include "interface/say-hello.h" LUMIERA_PLUGIN_INTERFACEHANDLE; diff --git a/tests/plugin/test-cpp-plugin/example_plugin.cpp b/tests/plugin/test-cpp-plugin/example-plugin.cpp similarity index 93% rename from tests/plugin/test-cpp-plugin/example_plugin.cpp rename to tests/plugin/test-cpp-plugin/example-plugin.cpp index 8a32ac8e7..62e88fa34 100644 --- a/tests/plugin/test-cpp-plugin/example_plugin.cpp +++ b/tests/plugin/test-cpp-plugin/example-plugin.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file example-plugin.cpp + ** Dummy C++ plug-in to cover the plugin loader for unit test + ** This file defines a Lumiera plug-in written in C++, + ** implementing the `lumieraorg_testhello` interface + ** @see test-interfaces.c + */ + #include "common/interface-descriptor.h" @@ -31,7 +38,7 @@ extern "C" { #include "common/interface.h" #include "common/interface-descriptor.h" -#include "interface/say_hello.h" +#include "interface/say-hello.h" } #include diff --git a/tests/testrunner.cpp b/tests/testrunner.cpp index ce0e2faed..475dd3c0d 100644 --- a/tests/testrunner.cpp +++ b/tests/testrunner.cpp @@ -21,6 +21,13 @@ * *****************************************************/ +/** @file testrunner.cpp + ** Lumiera unit test suite + ** A simple test runner application. + ** The build system will link the individual shared libraries with the test code + ** together with this translation unit into the executable `target/test-suite` + */ + #include "include/lifecycle.h" #include "lib/test/testoption.hpp" #include "lib/test/suite.hpp" diff --git a/tests/tool/vgsuppression.c b/tests/tool/vgsuppression.c index 852cc3bc4..846d034b1 100644 --- a/tests/tool/vgsuppression.c +++ b/tests/tool/vgsuppression.c @@ -19,6 +19,15 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ +/** @file vgsuppression.c + ** dummy executable to generate _valgrind suppressions_. + ** When running code under `valgrind` to detect memory leaks, typically a well known set + ** of false alarms will be reported. The reason is that some facilities, either implemented + ** by our own or from third party libraries, just choose never to free some working buffers. + ** To deal with this well known issue, `valgrind` allows to be "primed" with a specifically + ** crafted executable, which deliberately triggers just these false memory leak alarms. + */ + /* just place any problematic calls where valgrind whines about in main (with comments please) */