From ddc915db4152599ffa316922f976895a93cefc70 Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Thu, 3 Nov 2016 19:37:34 +0100
Subject: [PATCH] Doxygen: fill in missing file level headlines for the Backend

---
 src/backend/backend.c                     |  2 +-
 src/backend/backend.h                     |  2 +-
 src/backend/engine/engine-config.cpp      |  2 +-
 src/backend/engine/engine-config.h        |  2 +-
 src/backend/engine/scheduler-frontend.cpp |  2 +-
 src/backend/engine/scheduler-frontend.hpp |  3 ++-
 src/backend/enginefacade.cpp              |  8 +++++++-
 src/backend/enginefacade.hpp              |  5 ++++-
 src/backend/file-handling.c               |  2 +-
 src/backend/filedescriptor.c              |  5 +++--
 src/backend/filedescriptorregistry.c      |  3 ++-
 src/backend/filehandle.c                  |  3 ++-
 src/backend/filehandlecache.c             |  3 ++-
 src/backend/fileheader.c                  |  4 +++-
 src/backend/media-access-facade.cpp       |  5 ++++-
 src/backend/media-access-facade.hpp       |  8 +++++++-
 src/backend/mmap.c                        |  3 ++-
 src/backend/mmapcache.c                   |  3 ++-
 src/backend/mmapings.c                    |  3 ++-
 src/backend/netnodefacade.cpp             |  5 ++++-
 src/backend/netnodefacade.hpp             |  5 ++++-
 src/backend/real-clock.cpp                |  9 +++++++--
 src/backend/resourcecollector.c           |  3 ++-
 src/backend/resourcecollector.h           |  3 ++-
 src/backend/scriptrunnerfacade.cpp        |  6 +++++-
 src/backend/scriptrunnerfacade.hpp        |  5 ++++-
 src/backend/thread-wrapper.hpp            | 11 ++++++++++-
 src/backend/threadpool-init.cpp           |  2 +-
 src/backend/threadpool-init.hpp           |  2 +-
 src/backend/threadpool.c                  |  4 +++-
 src/backend/threadpool.h                  |  2 +-
 src/backend/threads.c                     |  3 ++-
 src/backend/threads.h                     |  5 ++++-
 33 files changed, 98 insertions(+), 35 deletions(-)

diff --git a/src/backend/backend.c b/src/backend/backend.c
index 02b959f21..a0f909b35 100644
--- a/src/backend/backend.c
+++ b/src/backend/backend.c
@@ -22,7 +22,7 @@
 
 
 /** @file backend.c
- ** TODO backend.c
+ ** Lumiera Backend: implementation of global initialisation and services.
  */
 
 
diff --git a/src/backend/backend.h b/src/backend/backend.h
index a02613c34..5eb00217f 100644
--- a/src/backend/backend.h
+++ b/src/backend/backend.h
@@ -22,7 +22,7 @@
 
 
 /** @file backend.h
- ** TODO backend.h
+ ** Lumiera Backend: global initialisation and definitions.
  */
 
 
diff --git a/src/backend/engine/engine-config.cpp b/src/backend/engine/engine-config.cpp
index 3d14a93ec..93b10528f 100644
--- a/src/backend/engine/engine-config.cpp
+++ b/src/backend/engine/engine-config.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file engine-config.cpp
- ** TODO engine-config.cpp
+ ** implementation of engine configuration and parametrisation
  */
 
 
diff --git a/src/backend/engine/engine-config.h b/src/backend/engine/engine-config.h
index b85a84b31..89df108a9 100644
--- a/src/backend/engine/engine-config.h
+++ b/src/backend/engine/engine-config.h
@@ -22,7 +22,7 @@
 
 
 /** @file engine-config.h
- ** TODO engine-config.h
+ ** access point to configuration of engine parameters
  */
 
 
diff --git a/src/backend/engine/scheduler-frontend.cpp b/src/backend/engine/scheduler-frontend.cpp
index 2e38a6bd0..7e4aff0c1 100644
--- a/src/backend/engine/scheduler-frontend.cpp
+++ b/src/backend/engine/scheduler-frontend.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file scheduler-frontend.cpp
- ** TODO scheduler-frontend.cpp
+ ** Scheduler service implementation
  */
 
 
diff --git a/src/backend/engine/scheduler-frontend.hpp b/src/backend/engine/scheduler-frontend.hpp
index ad8a4fb56..d0c841be9 100644
--- a/src/backend/engine/scheduler-frontend.hpp
+++ b/src/backend/engine/scheduler-frontend.hpp
@@ -22,7 +22,8 @@
 
 
 /** @file scheduler-frontend.hpp
- ** TODO scheduler-frontend.hpp
+ ** Scheduler service access point for higher layers.
+ ** @todo WIP unfinished since 9/2013
  */
 
 
diff --git a/src/backend/enginefacade.cpp b/src/backend/enginefacade.cpp
index 14aa9e0d1..75485cfe6 100644
--- a/src/backend/enginefacade.cpp
+++ b/src/backend/enginefacade.cpp
@@ -22,7 +22,13 @@
 
 
 /** @file enginefacade.cpp
- ** TODO 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
+ ** 
  */
 
 
diff --git a/src/backend/enginefacade.hpp b/src/backend/enginefacade.hpp
index 0a4d1604c..1d0634f59 100644
--- a/src/backend/enginefacade.hpp
+++ b/src/backend/enginefacade.hpp
@@ -22,7 +22,10 @@
 
 
 /** @file enginefacade.hpp
- ** TODO 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.
  */
 
 
diff --git a/src/backend/file-handling.c b/src/backend/file-handling.c
index beadd1b8f..1fd1a3861 100644
--- a/src/backend/file-handling.c
+++ b/src/backend/file-handling.c
@@ -22,7 +22,7 @@
 
 
 /** @file file-handling.c
- ** TODO file-handling.c
+ ** Implementation of file management functions
  */
 
 
diff --git a/src/backend/filedescriptor.c b/src/backend/filedescriptor.c
index c24847ca9..180bd5d13 100644
--- a/src/backend/filedescriptor.c
+++ b/src/backend/filedescriptor.c
@@ -22,7 +22,8 @@
 
 
 /** @file filedescriptor.c
- ** TODO filedescriptor.c
+ ** Implementation of a file descriptor management framework
+ ** @todo development in this area is stalled since 2010
  */
 
 
@@ -83,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 b9eb74657..8717d25e4 100644
--- a/src/backend/filedescriptorregistry.c
+++ b/src/backend/filedescriptorregistry.c
@@ -22,7 +22,8 @@
 
 
 /** @file filedescriptorregistry.c
- ** TODO filedescriptorregistry.c
+ ** Implementation of a registry to manage used filedescriptors
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/filehandle.c b/src/backend/filehandle.c
index 61fa6699a..4557bc558 100644
--- a/src/backend/filehandle.c
+++ b/src/backend/filehandle.c
@@ -22,7 +22,8 @@
 
 
 /** @file filehandle.c
- ** TODO filehandle.c
+ ** Implementation of filehandle representation.
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/filehandlecache.c b/src/backend/filehandlecache.c
index 7adc70664..2cd0046e5 100644
--- a/src/backend/filehandlecache.c
+++ b/src/backend/filehandlecache.c
@@ -22,7 +22,8 @@
 
 
 /** @file filehandlecache.c
- ** TODO filehandlecache.c
+ ** Implementation of caching for filehandle representation data
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/fileheader.c b/src/backend/fileheader.c
index 4df93a0f5..1fe269d76 100644
--- a/src/backend/fileheader.c
+++ b/src/backend/fileheader.c
@@ -22,7 +22,9 @@
 
 
 /** @file fileheader.c
- ** TODO 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
  */
 
 
diff --git a/src/backend/media-access-facade.cpp b/src/backend/media-access-facade.cpp
index 00906d0fd..889150272 100644
--- a/src/backend/media-access-facade.cpp
+++ b/src/backend/media-access-facade.cpp
@@ -22,7 +22,10 @@
 
 
 /** @file media-access-facade.cpp
- ** TODO 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.
  */
 
 
diff --git a/src/backend/media-access-facade.hpp b/src/backend/media-access-facade.hpp
index abfe4ae6b..c398f003d 100644
--- a/src/backend/media-access-facade.hpp
+++ b/src/backend/media-access-facade.hpp
@@ -22,7 +22,13 @@
 
 
 /** @file media-access-facade.hpp
- ** TODO 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.
  */
 
 
diff --git a/src/backend/mmap.c b/src/backend/mmap.c
index d5950fe90..fa9537ac0 100644
--- a/src/backend/mmap.c
+++ b/src/backend/mmap.c
@@ -22,7 +22,8 @@
 
 
 /** @file mmap.c
- ** TODO mmap.c
+ ** Implementation of management for memory mapped file regions
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/mmapcache.c b/src/backend/mmapcache.c
index 4b6c8f99b..9610579d6 100644
--- a/src/backend/mmapcache.c
+++ b/src/backend/mmapcache.c
@@ -22,7 +22,8 @@
 
 
 /** @file mmapcache.c
- ** TODO mmapcache.c
+ ** Implementation of caching for currently unused memory mapped file regions
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/mmapings.c b/src/backend/mmapings.c
index 8aab635b5..8107aa177 100644
--- a/src/backend/mmapings.c
+++ b/src/backend/mmapings.c
@@ -22,7 +22,8 @@
 
 
 /** @file mmapings.c
- ** TODO mmapings.c
+ ** Implementation of organisational data of memory mapped file regions
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/netnodefacade.cpp b/src/backend/netnodefacade.cpp
index a91662164..696081cf3 100644
--- a/src/backend/netnodefacade.cpp
+++ b/src/backend/netnodefacade.cpp
@@ -22,7 +22,10 @@
 
 
 /** @file netnodefacade.cpp
- ** TODO 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
  */
 
 
diff --git a/src/backend/netnodefacade.hpp b/src/backend/netnodefacade.hpp
index e759a579c..d4090c6b8 100644
--- a/src/backend/netnodefacade.hpp
+++ b/src/backend/netnodefacade.hpp
@@ -22,7 +22,10 @@
 
 
 /** @file netnodefacade.hpp
- ** TODO 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
  */
 
 
diff --git a/src/backend/real-clock.cpp b/src/backend/real-clock.cpp
index b7865c232..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 <Ichthyostega@web.de>
@@ -22,7 +22,12 @@
 
 
 /** @file real-clock.cpp
- ** TODO 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
  */
 
 
diff --git a/src/backend/resourcecollector.c b/src/backend/resourcecollector.c
index 48528977b..86a8411c0 100644
--- a/src/backend/resourcecollector.c
+++ b/src/backend/resourcecollector.c
@@ -22,7 +22,8 @@
 
 
 /** @file resourcecollector.c
- ** TODO 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
  */
 
 
diff --git a/src/backend/resourcecollector.h b/src/backend/resourcecollector.h
index af2a6665b..2108335e4 100644
--- a/src/backend/resourcecollector.h
+++ b/src/backend/resourcecollector.h
@@ -22,7 +22,8 @@
 
 
 /** @file resourcecollector.h
- ** TODO resourcecollector.h
+ ** A global manager for scarce system resources
+ ** @todo this was a plan from 2008 and never got beyond an initial concept stage
  */
 
 
diff --git a/src/backend/scriptrunnerfacade.cpp b/src/backend/scriptrunnerfacade.cpp
index 90663edd1..f745e3c70 100644
--- a/src/backend/scriptrunnerfacade.cpp
+++ b/src/backend/scriptrunnerfacade.cpp
@@ -22,7 +22,11 @@
 
 
 /** @file scriptrunnerfacade.cpp
- ** TODO 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
  */
 
 
diff --git a/src/backend/scriptrunnerfacade.hpp b/src/backend/scriptrunnerfacade.hpp
index 19a5cb40f..e6d46e58b 100644
--- a/src/backend/scriptrunnerfacade.hpp
+++ b/src/backend/scriptrunnerfacade.hpp
@@ -22,7 +22,10 @@
 
 
 /** @file scriptrunnerfacade.hpp
- ** TODO 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
  */
 
 
diff --git a/src/backend/thread-wrapper.hpp b/src/backend/thread-wrapper.hpp
index 7165d314f..689fa54e4 100644
--- a/src/backend/thread-wrapper.hpp
+++ b/src/backend/thread-wrapper.hpp
@@ -23,7 +23,16 @@
 
 
 /** @file thread-wrapper.hpp
- ** TODO 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.
  */
 
 
diff --git a/src/backend/threadpool-init.cpp b/src/backend/threadpool-init.cpp
index 296b65ade..2634d028c 100644
--- a/src/backend/threadpool-init.cpp
+++ b/src/backend/threadpool-init.cpp
@@ -22,7 +22,7 @@
 
 
 /** @file threadpool-init.cpp
- ** TODO threadpool-init.cpp
+ ** Implementation of automatic initialisation of the low-level thread handling framework.
  */
 
 
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 16c43e645..c00e94631 100644
--- a/src/backend/threadpool.c
+++ b/src/backend/threadpool.c
@@ -22,7 +22,9 @@
 
 
 /** @file threadpool.c
- ** TODO 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
  */
 
 
diff --git a/src/backend/threadpool.h b/src/backend/threadpool.h
index caecfd9db..4298ad74e 100644
--- a/src/backend/threadpool.h
+++ b/src/backend/threadpool.h
@@ -22,7 +22,7 @@
 
 
 /** @file threadpool.h
- ** TODO threadpool.h
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/threads.c b/src/backend/threads.c
index 46ad5083d..3c719eb13 100644
--- a/src/backend/threads.c
+++ b/src/backend/threads.c
@@ -22,7 +22,8 @@
 
 
 /** @file threads.c
- ** TODO threads.c
+ ** Implementation of Lumiera's low-level thread handling framework
+ ** @todo development in this area is stalled since 2010
  */
 
 
diff --git a/src/backend/threads.h b/src/backend/threads.h
index 454328ff5..cf30bcc69 100644
--- a/src/backend/threads.h
+++ b/src/backend/threads.h
@@ -22,7 +22,10 @@
 
 
 /** @file threads.h
- ** TODO 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
  */