Doxygen: supply missing file level comments for test support helpers

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

@@ -20,8 +20,12 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 

tests/core/proc/asset/testasset.cpp

@@ -20,8 +20,8 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testasset.cpp
+ ** Implementation of a mocked Asset for unit tests
  */
 
 

tests/core/proc/asset/testasset.hpp

@@ -20,8 +20,8 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testasset.hpp
+ ** A mock asset to support unit testing
  */
 
 

tests/core/proc/asset/testclipasset.hpp

@@ -20,8 +20,8 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testclipasset.hpp
+ ** A placeholder Clip asset to support unit testing
  */
 
 

tests/core/proc/engine/testframe.cpp

@@ -20,8 +20,8 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testframe.cpp
+ ** Implementation of fake data frames to support unit testing
  */
 
 

tests/core/proc/engine/testframe.hpp

@@ -20,8 +20,8 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testframe.hpp
+ ** Unit test helper to generate fake test data frames
  */
 
 

tests/core/proc/mobject/session/test-scope-invalid.hpp

@@ -20,8 +20,9 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file test-scope-invalid.hpp
+ ** Unit test helper to generate deliberately wrong placement scopes.
+ ** Usable to cover error handling related to QueryFocus and ScopePath
  */
 
 

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

@@ -20,8 +20,10 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 

tests/core/proc/mobject/session/test-scopes.hpp

@@ -20,8 +20,11 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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.
  */
 
 

tests/core/proc/mobject/session/testclip.cpp

@@ -20,8 +20,8 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testclip.cpp
+ ** Implementation of a stubbed clip object to support unit testing
  */
 
 

tests/core/proc/mobject/session/testclip.hpp

@@ -20,8 +20,8 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @file testclip.hpp
+ ** A stub implementation of the Clip interface for unit testing
  */
 
 

tests/core/proc/mobject/session/testroot.hpp

@@ -20,8 +20,10 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 

tests/core/proc/mobject/session/testsession1.hpp

@@ -20,8 +20,11 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 

tests/include/interface/say-hello.h

@@ -1,20 +1,20 @@
+/** @file say-hello.h
+ ** A mock interface to support testing of the interface system
+ */
+
+#ifndef TEST_INCLUDE_SAY_HELLO_H
+#define TEST_INCLUDE_SAY_HELLO_H
+
 #include "common/interface.h"
 
-/*
-  one interface which can greet in different languages
-*/
+/** mock interface which can greet in different languages */
 
-/** @file §§§
- ** unit test TODO §§§
- */
 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)),
 );

tests/library/test-target-obj.hpp

@@ -20,8 +20,10 @@
 
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 

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 <ct@pipapo.org>
@@ -20,8 +20,11 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 
@@ -30,7 +33,7 @@
 #include "common/interface-descriptor.h"
 #include "common/config-interface.h"
 
-#include "interface/say_hello.h"
+#include "interface/say-hello.h"
 
 
 LUMIERA_PLUGIN_INTERFACEHANDLE;

tests/plugin/test-cpp-plugin/example-plugin.cpp

@@ -21,8 +21,11 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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
  */
 
 
@@ -35,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 <iostream>

tests/testrunner.cpp

@@ -21,8 +21,11 @@
 
 * *****************************************************/
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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"

tests/tool/vgsuppression.c

@@ -19,8 +19,13 @@
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */
 
-/** @file §§§
- ** unit test TODO §§§
+/** @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.
  */
 
 /*