clean-up: some Doxygen improvements

- reorganise the navigation tab structure
- place all further index lists into a common "Index" tab
- include a list of concepts
- remove the various "member" sub-tabs, these are not helpful
- the "modules" tab is now called "topics" (since C++ has now Modules!)
- generally re-sync DoxygenLayout.xml with a current pristine template
- comb though the Doxygen Warnings and fix a lot of small problems

doc/devel/Doxyfile

@@ -157,7 +157,8 @@ REFERENCES_LINK_SOURCE = NO
 SOURCE_TOOLTIPS        = YES
 USE_HTAGS              = NO
 VERBATIM_HEADERS       = NO
-CLANG_ASSISTED_PARSING = YES
+#CLANG_ASSISTED_PARSING = YES
+CLANG_ASSISTED_PARSING = NO
 CLANG_OPTIONS          = -DDEBUG -DEBUG_ALPHA
 
 #---------------------------------------------------------------------------

doc/devel/DoxygenLayout.xml

@@ -2,42 +2,43 @@
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Lumiera API Documentation"/>
-    <tab type="user" url="http://Lumiera.org/documentation/user/intro/intro.html" title="Intro"/>
+    <tab type="user" url="/documentation/user/intro/intro.html" title="Intro"/>
-    <tab type="user" url="http://Lumiera.org/documentation/technical/overview.html" title="Overview"/>
+    <tab type="user" url="/documentation/technical/overview.html" title="Overview"/>
-    <tab type="modules" visible="yes" title="" intro="Subsystems"/>
+    <tab type="topics" visible="yes" title="" intro="Subsystems"/>
-    <tab type="classes" visible="yes" title="">
+    <tab type="classlist" visible="yes" title="Classes" intro=""/>
-      <tab type="classlist" visible="yes" title="" intro=""/>
+    <tab type="usergroup" title="Index">
-      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="filelist" visible="yes" title="Files" intro=""/>
-      <tab type="hierarchy" visible="no" title="" intro=""/>
+      <tab type="namespacelist" visible="yes" title="Namespaces" intro=""/>
-      <tab type="classmembers" visible="yes" title="" intro=""/>
+      <tab type="concepts" visible="yes" title="Concepts"/>
+      <tab type="structlist" visible="yes" title="" intro=""/>
+      <tab type="exceptionlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title="Class Idx"/>
+      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title="Interfaces"/>
+      <tab type="classmembers" visible="yes" title="Members" intro=""/>
     </tab>
-    <tab type="namespaces" visible="yes" title="">
+    <tab type="pages" visible="yes" title="" intro="Other">
-      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="examples" visible="yes" title="" intro=""/>
-      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+      <tab type="user" url="/documentation/design/" title="Design Topics"/>
     </tab>
-    <tab type="files" visible="yes" title="">
-      <tab type="filelist" visible="yes" title="" intro=""/>
-      <tab type="globals" visible="yes" title="" intro=""/>
-    </tab>
-    <tab type="pages" visible="yes" title="" intro=""/>
-    <tab type="examples" visible="yes" title="" intro=""/>
   </navindex>
 
   <!-- Layout definition for a class page -->
   <class>
     <briefdescription visible="no"/>
-    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includes visible="$SHOW_HEADERFILE"/>
     <allmemberslink visible="yes"/>
     <detaileddescription title="Description"/>
     <memberdecl>
+      <nestedclasses visible="yes" title=""/>
       <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
       <publicslots title=""/>
       <signals title=""/>
-      <publicmethods title=""/>
-      <publicstaticmethods title=""/>
       <publicstaticattributes title=""/>
       <publicattributes title=""/>
-      <nestedclasses visible="yes" title=""/>
+      <publicstaticmethods title=""/>
+      <publicmethods title=""/>
       <friends title=""/>
       <properties title=""/>
       <events title=""/>
@@ -62,13 +63,15 @@
       <membergroups visible="yes"/>
     </memberdecl>
     <memberdef>
+      <constructors title=""/>
+      <inlineclasses title=""/>
       <typedefs title=""/>
       <enums title=""/>
-      <inlineclasses title=""/>
-      <constructors title=""/>
       <functions title=""/>
       <properties title=""/>
+      <interfaces title=""/>
       <variables title=""/>
+      <services title=""/>
       <events title=""/>
       <related title=""/>
     </memberdef>
@@ -84,12 +87,18 @@
     <detaileddescription title="Description"/>
     <memberdecl>
       <nestednamespaces visible="yes" title=""/>
-      <typedefs title=""/>
+      <interfaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <typedefs visible="yes" title=""/>
       <enums title=""/>
       <classes visible="yes" title=""/>
       <functions title=""/>
       <variables title=""/>
+      <exceptions visible="yes" title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <membergroups visible="yes"/>
+      <constantgroups visible="yes" title=""/>
     </memberdecl>
     <memberdef>
       <typedefs title=""/>
@@ -97,24 +106,41 @@
       <inlineclasses title=""/>
       <functions title=""/>
       <variables title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
     </memberdef>
     <authorsection visible="yes"/>
   </namespace>
 
+  <!-- Layout definition for a concept page -->
+  <concept>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_HEADERFILE"/>
+    <detaileddescription title=""/>
+    <definition visible="yes" title=""/>
+    <authorsection visible="yes"/>
+  </concept>
+
   <!-- Layout definition for a file page -->
   <file>
-    <briefdescription visible="no"/>
+    <briefdescription visible="yes"/>
     <sourcelink visible="yes"/>
     <detaileddescription title="Description"/>
     <includes visible="$SHOW_INCLUDE_FILES"/>
     <memberdecl>
-      <classes visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <interfaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <defines title=""/>
       <typedefs title=""/>
       <enums title=""/>
-      <defines title=""/>
+      <classes visible="yes" title=""/>
       <functions title=""/>
       <variables title=""/>
-      <namespaces visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <constantgroups visible="yes" title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
     <memberdef>
@@ -134,14 +160,19 @@
   <group>
     <briefdescription visible="no"/>
     <detaileddescription title="Description"/>
+    <groupgraph visible="yes"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
       <dirs visible="yes" title=""/>
       <files visible="yes" title=""/>
+      <modules visible="yes" title=""/>
       <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
       <classes visible="yes" title=""/>
       <defines title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
       <functions title=""/>
@@ -160,6 +191,8 @@
       <inlineclasses title=""/>
       <defines title=""/>
       <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
       <enums title=""/>
       <enumvalues title=""/>
       <functions title=""/>
@@ -172,10 +205,28 @@
       <properties title=""/>
       <friends title=""/>
     </memberdef>
-    <groupgraph visible="$GROUP_GRAPHS"/>
     <authorsection visible="yes"/>
   </group>
 
+  <!-- Layout definition for a C++20 module page -->
+  <module>
+    <briefdescription visible="yes"/>
+    <exportedmodules visible="yes"/>
+    <memberdecl>
+      <concepts visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <enums title=""/>
+      <typedefs title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups title=""/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdecl>
+      <files visible="yes"/>
+    </memberdecl>
+  </module>
+
   <!-- Layout definition for a directory page -->
   <directory>
     <briefdescription visible="yes"/>

src/common/advice/advice.cpp

@@ -301,13 +301,8 @@ namespace advice {
    *  into an internal buffer within the AdviceSystem. We then use the
    *  Index to remember the presence of this advice data and to detect
    *  possible matches with existing advice::Request entries.
-   *  @param adviceData pointer to the copied data,
+   *  @param newProvision pointer to the copied data,
    *         actually pointing to an ActiveProvision<AD>
-   *  @return pointer to an superseded old provision entry,
-   *          which the caller then needs to de-allocate.
-   *          The caller is assumed to know the actual type
-   *          and thus the size of the entry to deallocate.
-   *          Returning `NULL` in case no old entry exists.
    */
   void
   AdviceLink::publishProvision (PointOfAdvice* newProvision)
@@ -323,9 +318,6 @@ namespace advice {
    *  after removing the provision index entry
    *  we also need to re-process any requests
    *  which happen to match our binding...
-   *  @return pointer to the existing provision entry,
-   *          to be deallocated by the caller, which
-   *          is assumed to know it's exact type.
    */
   void
   AdviceLink::discardSolutions ()

src/common/instancehandle.hpp

@@ -207,7 +207,7 @@ namespace lumiera {
       /** Set up an InstanceHandle managing the
        *  registration and deregistration of interface(s).
        *  Should be placed at the service providing side.
-       *  @param a (single) interface descriptor, which can be created with
+       *  @param descriptor a (single) interface descriptor, which can be created with
        *         LUMIERA_INTERFACE_INSTANCE and referred to by LUMIERA_INTERFACE_REF
        */
       InstanceHandle (LumieraInterface descriptor)

src/doxygen.dox

@@ -1,5 +1,5 @@
 /*
-  DOXYGEN.dox  -  font page for the Doxygen API documentation
+  DOXYGEN.dox  -  front page for the Doxygen API documentation
  
 
    Copyright (C)
@@ -46,7 +46,7 @@ with the *ASCIIDOC* tool and published at the [Lumiera website](http://Lumiera.o
   necessary to understand the actual code
 - right now, you are looking at the **API Documentation**, which is the entrance point to the actual code
 - on your exploration path down to the internal details, you might want to follow the overview given
-  + by the [Layer and Subsystem](modules.html) overview
+  + by the [Layer and Subsystem](topics.html) overview
   + the file level comments of relevant interfaces
 
 */
@@ -54,13 +54,24 @@ with the *ASCIIDOC* tool and published at the [Lumiera website](http://Lumiera.o
 /* ==== Layers ==== */
 
 /** @defgroup vault Vault-Layer
-*/
+ *   Provides the technical services for all processing and system access.
+ *   Manages worker pools, schedules jobs, does the memory management for the
+ *   heavy multimedia data. Loads and delegates to external libraries for
+ *   media processing.
+ */
 
 /** @defgroup steam Steam-Layer
-*/
+ *   Keeps the Session, generates the rendering graphs for sequences,
+ *   arranges what to do when and how, coordinates command/event processing,
+ *   playback and rendering.
+ */
 
 /** @defgroup gui Graphical User Interface
-*/
+ *   Interaction and Presentation layer.
+ *   Provides the structures to coordinate navication, presentation state
+ *   and gestures. Defines the widgets and controllers for the UI.
+ *   Loaded as Plug-in.
+ */
 
 /* ==== Subsystems ==== */
 
@@ -86,6 +97,10 @@ with the *ASCIIDOC* tool and published at the [Lumiera website](http://Lumiera.o
 
 /** @defgroup scheduler Scheduler
     @ingroup vault
+    The Scheduler acts as the central hub in the implementation of the RenderEngine
+    and coordinates the processing resources of the application. A Render Job is created
+    for every frame and passed to the Scheduler, marked with a deadline, and connected
+    to _prerequisite_ jobs.
 */
 
 /** @defgroup memory Memory Management

src/include/display-handles.hpp

@@ -11,7 +11,7 @@
 
 */
 
-/** @file display-handles.h
+/** @file display-handles.hpp
  ** Opaque handles and similar typedefs used to communicate via the
  ** lumiera::Display and lumiera::DummyPlayer facade interfaces.
  ** 

src/lib/diff/diff-language.hpp

@@ -272,9 +272,9 @@ namespace diff{
   /**
    * generic builder to apply a diff description to a given target data structure.
    * The usage pattern is as follows
-   * #. construct a DiffApplicator instance, wrapping the target data
+   * -# construct a DiffApplicator instance, wrapping the target data
-   * #. feed the diff (sequence of diff verbs) to the #consume function
+   * -# feed the diff (sequence of diff verbs) to the #consume function
-   * #. the wrapped target data has been altered, to conform to the given diff
+   * -# the wrapped target data has been altered, to conform to the given diff
    * @note a suitable DiffApplicationStrategy will be picked, based on the type
    *       of the concrete target sequence given at construction. (Effectively
    *       this means you need a suitable DiffApplicationStrategy specialisation,

src/lib/meta/tuple-helper.hpp

@@ -19,7 +19,7 @@
  ** helpers to build tuple types from metaprogramming and to pretty-print tuples.
  ** 
  ** Notably, a `concept tuple_like` is provided, which is satisfied for any type in compliance
- ** with the »tuple protocol«. Together with a [generic accessor][\ref lib::meta::getElm),
+ ** with the »tuple protocol«. Together with a [generic accessor][\ref lib::meta::getElm],
  ** this allows to handle all _tuple-like_ types uniformly.
  ** @note Due to an unfortunate limitation of the standard, we're forced to provide our own alternative
  **       implementation to replace `std::apply`, so that a function can be applied to any _tuple-like_

src/lib/multifact.hpp

@@ -283,7 +283,7 @@ namespace lib {
          * Select a production line and invoke the fabrication function.
          * @param id select the actual pre installed fabrication function to use
          * @param args additional arguments to pass to the fabrication.
-         * @note the template parameter #SIG defines the raw or nominal signature
+         * @note the template parameter \a SIG defines the raw or nominal signature
          *       of the fabrication, and especially the number of arguments
          * @return the created product, after passing through the #Wrapper functor
          */

src/lib/random-draw.hpp

@@ -17,7 +17,8 @@
  ** value with a limited target domain. The intended usage scenario is to parametrise some
  ** configuration or computation »randomly«, with well defined probabilities and value ranges.
  ** A DSL is provided to simplify the common configuration and value mapping scenarios.
- ** @paragraph The underlying implementation was extracted 11/2023 from (and later used by)
+ ** \par motivation
+ **     The underlying implementation was extracted 11/2023 from (and later used by)
  **     TestChainLoad; there, random numbers are derived from node hash values and must be mapped
  **     to yield control parameters governing the topology of a DAG datastructure. Notably, a
  **     draw is performed on each step to decide if the graph should fork. While numerically

src/lib/scoped-ptrvect.hpp

@@ -145,7 +145,7 @@ namespace lib {
        *  This object will be removed form this collection
        *  and returned as-is; it won't be deleted when the
        *  ScopedPtrVect goes out of scope.
-       * @param obj address of the object in question.
+       * @param objAddress address of the object in question.
        * @return pointer to the object, if found.
        *         Otherwise, NULL will be returned and the
        *         collection of managed objects remains unaltered

src/lib/split-splice.hpp

@@ -85,7 +85,7 @@ namespace lib {
   namespace error = lumiera::error;
   
   
-  namespace splitsplice {/// Implementation of [»SplitSplice« algorithm](\ref splite-splice.hpp)
+  namespace splitsplice {/// Implementation of [»SplitSplice« algorithm](\ref split-splice.hpp)
     
     
     /**

src/lib/test/microbenchmark-adaptor.hpp

@@ -13,7 +13,7 @@
 
 
 /** @file microbenchmark-adaptor.hpp
- ** Helpers and wrappers so simplify usage of \ref micobenchmark.hpp.
+ ** Helpers and wrappers so simplify usage of \ref microbenchmark.hpp.
  ** Notably the benchmark functions expect the actual »test subject« as a
  ** function or lambda with signature `size_t(size_t)`. The argument will be
  ** the loop index and the result value will be added into a checksum, which

src/lib/text-template-gen-node-binding.hpp

@@ -66,7 +66,7 @@ namespace lib {
     /**
      * Data-binding for a tree of GenNode data (ETD).
      * Attributes are accessible as keys, while iteration descends
-     * into the child scope of the attribute indicated in the ${for <key>}` tag.
+     * into the child scope of the attribute indicated in the `${for <key>}` tag.
      * @see TextTemplate_test::verify_ETD_binding()
      */
     template<>

src/lib/time/formats.hpp

@@ -211,7 +211,7 @@ namespace time {
         
       public:
         /** build a new Descriptor to denote support for all the Formats,
-         *  @param TY typelist holding all the Format types to support
+         *  @tparam TY typelist holding all the Format types to support
          */
         template<typename TY>
         static Supported

src/lib/time/quantiser.cpp

@@ -249,7 +249,7 @@ namespace time {
    * @remark This function reverses building the drop-frame timecode,
    *         and thus maps a time into consecutive frame numbers
    *         at NTSC framerate (i.e. without gaps)
-   * @param  timecode represented as time value in µ-ticks
+   * @param  time represented as time value in µ-ticks
    * @return the absolute frame number as addressed by NTSC drop-frame
    * @todo 2011 I doubt this works correct for negative times!!
    */

src/lib/time/timecode.cpp

@@ -213,7 +213,7 @@ namespace time {
     /** handle the limits of SMPTE timecode range.
      *  This is an extension and configuration point to control how
      *  to handle values beyond the official SMPTE timecode range of
-     *  0:0:0:0 to 23:59:59:##. When this strategy function is invoked,
+     *  `0:0:0:0` to `23:59:59:##`. When this strategy function is invoked,
      *  the frames, seconds, minutes and hours fields have already been processed
      *  and stored into the component digxels, under the assumption the overall
      *  value stays in range.

src/stage/ctrl/bus-term.hpp

@@ -40,8 +40,8 @@
  **       which is constructed in a way to ensure it is always has a
  **       bidirectional communication link to the Nexus.
  ** 
- ** @see [BusTerm_test]
+ ** @see \ref BusTerm_test
- ** @see Tangible
+ ** @see \ref Tangible
  ** 
  */
 

src/stage/ctrl/ui-manager.cpp

@@ -153,7 +153,7 @@ namespace ctrl {
   /**
    * @remarks moves the given operation into our private dispatcher queue and then
    *          schedules dequeuing and invocation into the UI event thread.
-   * @param op a completely closed lambda or functor
+   * @param task a completely closed lambda or functor
    * @warning closure need to be by value or equivalent, since
    *          the operation will be executed within another call stack
    */

src/stage/dialog/name-chooser.hpp

@@ -45,7 +45,7 @@ namespace dialog {
        * Creates a name chooser dialog.
        * @param parent The window which will be the parent of this dialog.
        * @param title The string for the title of this dialog.
-       * @param default_name The name that will be shown by default in the
+       * @param defaultName The name that will be shown by default in the
        * edit box of the dialog.
        */
       NameChooser(Gtk::Window &parent, cuString title, cuString defaultName);

src/stage/interact/ui-location-solver.hpp

@@ -243,7 +243,7 @@ namespace interact {
       /**
        * Solve for a location according to the given location rule.
        * @param depth desired kind of UI element (and thus the depth in the UI topology tree)
-       * @param elementType designator of the specific element to be created at that level
+       * @param elementTypeID designator of the specific element to be created at that level
        * @return an explicit location, resolved against the current UI topology. May be empty
        * @remarks the returned path is either empty (no solution exists), or it is "partially covered"
        *        by the existing UI; here, the "covered" part are the already existing UI elements,

src/stage/model/tangible.hpp

@@ -235,7 +235,7 @@ namespace model {
   
   
   /** convenience shortcut to build a message suitable for command invocation
-   * @param args... sequence of arguments to be packaged into a lib::diff::Rec for invocation
+   * @param args ... sequence of arguments to be packaged into a lib::diff::Rec for invocation
    */
   template<typename...ARGS>
   inline lib::diff::GenNode

src/stage/output/xv-displayer.cpp

@@ -14,7 +14,7 @@
 * *****************************************************************/
 
 
-/** @file xvdisplayer.cpp
+/** @file xv-displayer.cpp
  ** Implementation of video output via XVideo
  ** @todo WIP as of 5/2025 -- attempt to port this component to GTK-3 ///////////////////////////////////////TICKET #1403
  */

src/steam/fixture/segmentation.cpp

@@ -46,7 +46,7 @@ namespace fixture {
   /**
    * @param start (optional) definition of the new Segment's start point (inclusive)
    * @param after (optional) definition of the end point (exclusive)
-   * @param jobTicket specification of provided render functionality for the new Segment
+   * @param modelLink specification of provided render functionality for the new Segment
    * @remarks missing definitions will be derived or interpolated according to context
    *   - if start point is omitted, the new Segment will start seamlessly after
    *     any preceding Segment's end, in case this preceding Segment ends earlier

tests/library/diff/diff-complex-application-test.cpp

@@ -291,7 +291,7 @@ namespace test{
    * @see DiffTreeApplication_test generic variant of tree diff application
    * @see TreeMutatorBinding_test coverage of the "building blocks"
    * @see TreeMutator_test base operations of the adapter
-   * @see diff-tree-application.hpp
+   * @see tree-diff-application.hpp
    * @see tree-diff.hpp
    */
   class DiffComplexApplication_test

tests/library/diff/diff-ignore-changes-test.cpp

@@ -72,7 +72,7 @@ namespace test{
    * 
    * @see DiffComplexApplication_test test case which _indeed does a lot..._
    * @see TreeMutator_test base operations of the adapter
-   * @see diff-tree-application.hpp
+   * @see tree-diff-application.hpp
    * @see tree-diff.hpp
    */
   class DiffIgnoreChanges_test

tests/library/diff/diff-tree-application-simple-test.cpp

@@ -85,7 +85,7 @@ namespace test{
    * @see GenericRecord_test
    * @see GenNode_test
    * @see DiffListApplication_test
-   * @see diff-tree-application.hpp
+   * @see tree-diff-application.hpp
    * @see tree-diff.hpp
    * @see tree-diff-traits.hpp
    */

tests/library/diff/diff-tree-application-test.cpp

@@ -98,7 +98,7 @@ namespace test{
    * @see GenericRecord_test
    * @see GenNode_test
    * @see DiffListApplication_test
-   * @see diff-tree-application.hpp
+   * @see tree-diff-application.hpp
    * @see tree-diff.hpp
    */
   class DiffTreeApplication_test