From 42d97f6cf6ac4263b5b4d7cf60e086125aaa8c02 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Wed, 22 Feb 2017 01:58:49 +0100 Subject: [PATCH] Doxygen: supply missing file level comments for test support helpers --- tests/core/backend/media-access-mock.hpp | 8 ++++++-- tests/core/proc/asset/testasset.cpp | 4 ++-- tests/core/proc/asset/testasset.hpp | 4 ++-- tests/core/proc/asset/testclipasset.hpp | 4 ++-- tests/core/proc/engine/testframe.cpp | 4 ++-- tests/core/proc/engine/testframe.hpp | 4 ++-- .../mobject/session/test-scope-invalid.hpp | 5 +++-- .../core/proc/mobject/session/test-scopes.cpp | 6 ++++-- .../core/proc/mobject/session/test-scopes.hpp | 7 +++++-- tests/core/proc/mobject/session/testclip.cpp | 4 ++-- tests/core/proc/mobject/session/testclip.hpp | 4 ++-- tests/core/proc/mobject/session/testroot.hpp | 6 ++++-- .../core/proc/mobject/session/testsession1.hpp | 7 +++++-- .../interface/{say_hello.h => say-hello.h} | 18 +++++++++--------- tests/library/test-target-obj.hpp | 6 ++++-- .../{example_plugin.c => example-plugin.c} | 11 +++++++---- .../{example_plugin.cpp => example-plugin.cpp} | 9 ++++++--- tests/testrunner.cpp | 7 +++++-- tests/tool/vgsuppression.c | 9 +++++++-- 19 files changed, 79 insertions(+), 48 deletions(-) rename tests/include/interface/{say_hello.h => say-hello.h} (56%) rename tests/plugin/test-c-plugin/{example_plugin.c => example-plugin.c} (96%) rename tests/plugin/test-cpp-plugin/{example_plugin.cpp => example-plugin.cpp} (93%) diff --git a/tests/core/backend/media-access-mock.hpp b/tests/core/backend/media-access-mock.hpp index 17c3ed267..f44e9060e 100644 --- a/tests/core/backend/media-access-mock.hpp +++ b/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 */ diff --git a/tests/core/proc/asset/testasset.cpp b/tests/core/proc/asset/testasset.cpp index 3342d5e74..57ef73c30 100644 --- a/tests/core/proc/asset/testasset.cpp +++ b/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 */ diff --git a/tests/core/proc/asset/testasset.hpp b/tests/core/proc/asset/testasset.hpp index 689b1262e..12d4b494f 100644 --- a/tests/core/proc/asset/testasset.hpp +++ b/tests/core/proc/asset/testasset.hpp @@ -20,8 +20,8 @@ */ -/** @file §§§ - ** unit test TODO §§§ +/** @file testasset.hpp + ** A mock asset to support unit testing */ diff --git a/tests/core/proc/asset/testclipasset.hpp b/tests/core/proc/asset/testclipasset.hpp index e31616f8d..b10925925 100644 --- a/tests/core/proc/asset/testclipasset.hpp +++ b/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 */ diff --git a/tests/core/proc/engine/testframe.cpp b/tests/core/proc/engine/testframe.cpp index 3b58924a6..1682fdb4e 100644 --- a/tests/core/proc/engine/testframe.cpp +++ b/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 */ diff --git a/tests/core/proc/engine/testframe.hpp b/tests/core/proc/engine/testframe.hpp index a124f4e1b..e39be683e 100644 --- a/tests/core/proc/engine/testframe.hpp +++ b/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 */ diff --git a/tests/core/proc/mobject/session/test-scope-invalid.hpp b/tests/core/proc/mobject/session/test-scope-invalid.hpp index 24c302658..b0a1849f6 100644 --- a/tests/core/proc/mobject/session/test-scope-invalid.hpp +++ b/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 */ diff --git a/tests/core/proc/mobject/session/test-scopes.cpp b/tests/core/proc/mobject/session/test-scopes.cpp index 5e86d4397..b7374d926 100644 --- a/tests/core/proc/mobject/session/test-scopes.cpp +++ b/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 */ diff --git a/tests/core/proc/mobject/session/test-scopes.hpp b/tests/core/proc/mobject/session/test-scopes.hpp index 1702a30e1..eb9d49d77 100644 --- a/tests/core/proc/mobject/session/test-scopes.hpp +++ b/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. */ diff --git a/tests/core/proc/mobject/session/testclip.cpp b/tests/core/proc/mobject/session/testclip.cpp index b275f7753..9edd7df3f 100644 --- a/tests/core/proc/mobject/session/testclip.cpp +++ b/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 */ diff --git a/tests/core/proc/mobject/session/testclip.hpp b/tests/core/proc/mobject/session/testclip.hpp index 5a6d327f9..dcd3adef1 100644 --- a/tests/core/proc/mobject/session/testclip.hpp +++ b/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 */ diff --git a/tests/core/proc/mobject/session/testroot.hpp b/tests/core/proc/mobject/session/testroot.hpp index 8c1474675..93d539d3b 100644 --- a/tests/core/proc/mobject/session/testroot.hpp +++ b/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 */ diff --git a/tests/core/proc/mobject/session/testsession1.hpp b/tests/core/proc/mobject/session/testsession1.hpp index 3e0f1fcf2..1d47c7ea7 100644 --- a/tests/core/proc/mobject/session/testsession1.hpp +++ b/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 */ diff --git a/tests/include/interface/say_hello.h b/tests/include/interface/say-hello.h similarity index 56% rename from tests/include/interface/say_hello.h rename to tests/include/interface/say-hello.h index d9696e57b..d94acd8ad 100644 --- a/tests/include/interface/say_hello.h +++ b/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)), ); diff --git a/tests/library/test-target-obj.hpp b/tests/library/test-target-obj.hpp index 2e5412fb8..d09b5a598 100644 --- a/tests/library/test-target-obj.hpp +++ b/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 */ 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 d67c80156..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,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; 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 552a26c2f..62e88fa34 100644 --- a/tests/plugin/test-cpp-plugin/example_plugin.cpp +++ b/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 diff --git a/tests/testrunner.cpp b/tests/testrunner.cpp index 8c9c91d24..475dd3c0d 100644 --- a/tests/testrunner.cpp +++ b/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" diff --git a/tests/tool/vgsuppression.c b/tests/tool/vgsuppression.c index 82f7ff474..846d034b1 100644 --- a/tests/tool/vgsuppression.c +++ b/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. */ /*