diff --git a/src/common/guifacade.cpp b/src/common/guifacade.cpp
index bde729f1e..25779272a 100644
--- a/src/common/guifacade.cpp
+++ b/src/common/guifacade.cpp
@@ -24,7 +24,7 @@
 /** @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()
+ ** the [Subsystem descriptor](\ref 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.
diff --git a/src/common/query/query-resolver.hpp b/src/common/query/query-resolver.hpp
index 52ea1f231..0a6f2759d 100644
--- a/src/common/query/query-resolver.hpp
+++ b/src/common/query/query-resolver.hpp
@@ -96,7 +96,7 @@ namespace lumiera {
   /**
    * Interface: a facility for resolving (some kind of) queries
    * A concrete subclass has the ability to create Resolution instances
-   * in response to specific queries of some kind, [if applicable](QueryResolver::canHandle).
+   * in response to specific queries of some kind, [if applicable](\ref QueryResolver::canHandle).
    * Every resolution mechanism is expected to enrol by calling #installResolutionCase.
    * Such a registration is considered permanent; a factory function gets stored,
    * assuming that the entity to implement this function remains available
diff --git a/src/gui/ctrl/bus-term.hpp b/src/gui/ctrl/bus-term.hpp
index b2deb406d..d4b6f918c 100644
--- a/src/gui/ctrl/bus-term.hpp
+++ b/src/gui/ctrl/bus-term.hpp
@@ -34,7 +34,7 @@
  ** which it will be wired. Moreover, each BusTerm bears a distinct
  ** [identity](\ref BusTerm::endpointID_), which is used as _implicit subject_
  ** for emanating messages, or as explicit destination for routing.
- ** The whole [UI-Bus](ui-bus.hpp) is built to perform within the
+ ** The whole [UI-Bus](\ref ui-bus.hpp) is built to perform within the
  ** UI event thread and thus is _not threadsafe_. For that reason,
  ** the automatic detachment built into each BusTerm's dtor is
  ** sufficient to ensure sane connectivity.
diff --git a/src/gui/ctrl/core-service.hpp b/src/gui/ctrl/core-service.hpp
index 61cb7775a..8c23fc7b7 100644
--- a/src/gui/ctrl/core-service.hpp
+++ b/src/gui/ctrl/core-service.hpp
@@ -47,8 +47,8 @@
  ** routing table in Nexus, can be addressed as a _first class citizen,_
  ** that is, we're able to direct messages towards such an element, knowing
  ** only it's ID. But there is a twist: all connections to the Bus are made
- ** from [bus terminals](ctrl::BusTerm), and each _node_, i.e. each
- ** [tangible model element](model::Tangible) has a BusTerm member and
+ ** from [bus terminals](\ref ctrl::BusTerm), and each _node_, i.e. each
+ ** [tangible model element](\ref model::Tangible) has a BusTerm member and
  ** thus inherits the ability to talk to the bus. But only when _actively_
  ** connected to the bus, a full link and entry in the routing table is
  ** established. The constructor of model::Tangible indeed makes such
@@ -65,8 +65,8 @@
  ** for the Nexus, and thus gains the ability to respond to those few special
  ** messages, which can not be handled in a generic way on the Nexus:
  ** - *act* handles command invocation within the Session core, and
- **   is treated by [forwarding](command-handler.hpp) it over the
- **   SessionCommand facade to the [Proc-Dispatcher](proc-dispatcher.hpp)
+ **   is treated by [forwarding](\ref command-handler.hpp) it over the
+ **   SessionCommand facade to the [Proc-Dispatcher](\ref proc-dispatcher.hpp)
  ** - *note* observes and captures presentation state note messages, which
  **   are to be handled by a central presentation state manager (TODO 1/17).
  ** 
diff --git a/src/gui/ctrl/nexus.hpp b/src/gui/ctrl/nexus.hpp
index eab41a8ea..205c88dd2 100644
--- a/src/gui/ctrl/nexus.hpp
+++ b/src/gui/ctrl/nexus.hpp
@@ -23,8 +23,8 @@
 
 /** @file nexus.hpp
  ** Core hub and routing table of the UI-Bus.
- ** Any relevant element within the Lumiera GTK UI is connected to the [UI-Bus](ui-bus.hpp)
- ** through some [bus terminal](bus-term.hpp). Actually, there is one special BustTerm
+ ** Any relevant element within the Lumiera GTK UI is connected to the [UI-Bus](\ref ui-bus.hpp)
+ ** through some [bus terminal](\ref bus-term.hpp). Actually, there is one special BustTerm
  ** implementation, which acts as router and messaging hub.
  ** 
  ** @note messages to unknown target elements are silently dropped.
diff --git a/src/gui/interact/view-locator.cpp b/src/gui/interact/view-locator.cpp
index ecfb2e848..350864201 100644
--- a/src/gui/interact/view-locator.cpp
+++ b/src/gui/interact/view-locator.cpp
@@ -23,8 +23,8 @@
 
 /** @file view-locator.cpp
  ** Implementation details of a machinery to allocate UI global component views.
- ** Essentially this compilation unit hosts the implementation backing the [ViewSpec-DSL](view-spec-dsl.hpp)
- ** and the [Location Solver](ui-location-solver.hpp) to drive evaluation of the standard location defaults,
+ ** Essentially this compilation unit hosts the implementation backing the [ViewSpec-DSL](\ref view-spec-dsl.hpp)
+ ** and the [Location Solver](\ref ui-location-solver.hpp) to drive evaluation of the standard location defaults,
  ** which are [hard-wired into the UI](\ref id-scheme.hpp). For this integration of various facilities and
  ** frameworks we rely on actual definitions for the DSL-tokens, which themselves are functors and tied by
  ** lambda-binding into the implementation side of ViewLocator; which both acts as a front-end to access
diff --git a/src/gui/interact/view-spec-dsl.hpp b/src/gui/interact/view-spec-dsl.hpp
index 120be8581..1a0dd6b2e 100644
--- a/src/gui/interact/view-spec-dsl.hpp
+++ b/src/gui/interact/view-spec-dsl.hpp
@@ -84,7 +84,7 @@
  **   This results in calling a dedicated _view allocator_ to create a new view or re-use an existing one
  **   as appropriate.
  ** 
- ** @note the actual binding for the DSL tokens can be found in the [ViewLocator implementation](view-locator.cpp)
+ ** @note the actual binding for the DSL tokens can be found in the [ViewLocator implementation](\ref view-locator.cpp)
  ** 
  ** @see ViewSpecDSL_test
  ** @see id-scheme.hpp
diff --git a/src/gui/model/tangible.cpp b/src/gui/model/tangible.cpp
index dc6e95d39..e81daf3dd 100644
--- a/src/gui/model/tangible.cpp
+++ b/src/gui/model/tangible.cpp
@@ -25,7 +25,7 @@
  ** Common base implementation of all tangible and connected interface elements.
  ** 
  ** @see abstract-tangible-test.cpp
- ** @see [explanation of the fundamental interactions](tangible.hpp)
+ ** @see [explanation of the fundamental interactions](\ref tangible.hpp)
  ** 
  */
 
diff --git a/src/gui/model/tangible.hpp b/src/gui/model/tangible.hpp
index 170d14e62..fb07452a4 100644
--- a/src/gui/model/tangible.hpp
+++ b/src/gui/model/tangible.hpp
@@ -24,7 +24,7 @@
 /** @file tangible.hpp
  ** Abstraction: a tangible element of the User Interface.
  ** This is a generic foundation for any elements of more than local relevance
- ** within the Lumiera UI.<br/> Any such element is connected to the [UI-Bus](ui-bus.hpp).
+ ** within the Lumiera UI.<br/> Any such element is connected to the [UI-Bus](\ref ui-bus.hpp).
  ** 
  ** ## rationale
  ** 
@@ -96,7 +96,7 @@
  ** 
  ** And finally, there are the _essential updates_ -- any changes in the model _for real._
  ** These are sent as notifications just to some relevant top level element, expecting this element
- ** to request a [diff](tree-diff.hpp) and to mutate contents into shape recursively.
+ ** to request a [diff](\ref tree-diff.hpp) and to mutate contents into shape recursively.
  ** 
  ** ## Interactions
  ** 
@@ -154,9 +154,9 @@ namespace model {
    * Interface common to all UI elements of relevance for the Lumiera application.
    * Any non-local and tangible interface interaction will at some point pass through
    * this foundation element, which forms the joint and attachment to the UI backbone,
-   * which is the [UI-Bus](ui-bus.hpp). Any tangible element acquires a distinct identity
+   * which is the [UI-Bus](\ref ui-bus.hpp). Any tangible element acquires a distinct identity
    * and has to be formed starting from an already existing bus nexus.
-   * @see [explanation of the basic interactions](tangible.hpp)
+   * @see [explanation of the basic interactions](\ref tangible.hpp)
    * @warning Tangible is `NonCopyable` for good reason: the UI-Bus Nexus adds a direct
    *          reference into the routing table, tied to the given Tangible's ID (identity.
    *          Consequently you must not store tangibles in STL containers, since these
diff --git a/src/gui/notification-service.cpp b/src/gui/notification-service.cpp
index f3cdc5032..2862a1fb2 100644
--- a/src/gui/notification-service.cpp
+++ b/src/gui/notification-service.cpp
@@ -273,7 +273,7 @@ namespace gui {
   
   
   /**
-   * When started, NotificationService connects to the [UI-Bus](ui-bus.hpp) via the provided connection.
+   * When started, NotificationService connects to the [UI-Bus](\ref ui-bus.hpp) via the provided connection.
    * This is a simple, unidirectional up-link connection, without actively adding NotificationService
    * into the routing tables in [Nexus]. Yet this simple connection is sufficient to implement this
    * service by talking to other facilities within the UI layer.
diff --git a/src/gui/notification-service.hpp b/src/gui/notification-service.hpp
index 93dd82666..20ea60c9f 100644
--- a/src/gui/notification-service.hpp
+++ b/src/gui/notification-service.hpp
@@ -68,7 +68,7 @@ namespace gui {
    * route calls through this interface.
    * 
    * @note the ctor of this class establishes an "up-link"
-   *       connection to the [UI-Bus](ui-bus.hpp), which
+   *       connection to the [UI-Bus](\ref ui-bus.hpp), which
    *       enables the service implementation to talk to
    *       other facilities within the UI.
    */
diff --git a/src/gui/timeline/header-pane-widget.hpp b/src/gui/timeline/header-pane-widget.hpp
index fdc44d0a0..ef4bf8a29 100644
--- a/src/gui/timeline/header-pane-widget.hpp
+++ b/src/gui/timeline/header-pane-widget.hpp
@@ -33,7 +33,7 @@
  ** The HeaderPaneWidget aggregates those patchbay elements into a nested, collapsable tree
  ** structure in accordance with the nesting of scopes. For the actual layout, it has to collaborate
  ** with the timeline::LayoutManager to work out the space available for each individual track head
- ** and to keep these parts aligned with the tracks in the [timeline body](BodyCanvasWidget).
+ ** and to keep these parts aligned with the tracks in the [timeline body](\ref BodyCanvasWidget).
  ** 
  ** @todo WIP-WIP-WIP as of 12/2016
  ** 
diff --git a/src/gui/timeline/layout-manager.hpp b/src/gui/timeline/layout-manager.hpp
index e73d52384..fb13c20f3 100644
--- a/src/gui/timeline/layout-manager.hpp
+++ b/src/gui/timeline/layout-manager.hpp
@@ -57,7 +57,7 @@
  ** 
  ** Whenever the layout of timeline contents has to be (re)established, we trigger a recursive
  ** evaluation pass, which in fact is a tree walk. The layout manager creates a DisplayEvaluation
- ** record, which is passed to the [Element's allocate function](Element::allocate). The element
+ ** record, which is passed to the [Element's allocate function](\ref Element::allocate). The element
  ** in turn has the liability to walks its children and recursively initiate a nested evaluation
  ** by invoking DisplayEvaluation::evaluateChild(Element), which in turn calls back to
  ** LayoutManager::evaluate() to initiate a recursive evaluation pass. Within the recursively
diff --git a/src/gui/timeline/timeline-controller.hpp b/src/gui/timeline/timeline-controller.hpp
index 75cb0f854..23b78b782 100644
--- a/src/gui/timeline/timeline-controller.hpp
+++ b/src/gui/timeline/timeline-controller.hpp
@@ -77,7 +77,7 @@ namespace timeline {
   
   /**
    * Controller to supervise the timeline display.
-   * As a [tangible element](model::Tangible), it is attached to the UI-Bus.
+   * As a [tangible element](\ref model::Tangible), it is attached to the UI-Bus.
    * @todo WIP-WIP-rewrite as of 12/2016
    * @remarks a Timeline always has an attached Sequence, which in turn has
    *     a single mandatory root track. This in turn might hold further child tracks,
diff --git a/src/gui/timeline/timeline-widget.hpp b/src/gui/timeline/timeline-widget.hpp
index 1128cf871..f968b3849 100644
--- a/src/gui/timeline/timeline-widget.hpp
+++ b/src/gui/timeline/timeline-widget.hpp
@@ -38,7 +38,7 @@
  ** the [UI-Bus](\ref ui-bus.hpp). So there will be a _parent element,_ corresponding to the
  ** ["model root"](\ref session::Root), and this parent, in response to some mutation message,
  ** will create a TimelineWidget, add it into the appropriate GTK display setup and manage it
- ** as child element; the [construction parameters](TimelineWidget::TimelineWidget] ensure
+ ** as child element; the [construction parameters](\ref TimelineWidget::TimelineWidget] ensure
  ** it gets connected to the bus as well. Incidentally, this assumption also implies that
  ** this parent element has set up a _binding for diff mutation,_ typically by implementing
  ** model::Tangible::buildMutator. And further on this means that the parent will also
diff --git a/src/gui/timeline/track-body.hpp b/src/gui/timeline/track-body.hpp
index 5e271115f..df8479122 100644
--- a/src/gui/timeline/track-body.hpp
+++ b/src/gui/timeline/track-body.hpp
@@ -29,7 +29,7 @@
  ** yet for coordination of a globally consistent timeline layout, each
  ** track display is coordinated by a TrackPresenter, which corresponds
  ** to a session::Fork and directly controls the respective display elements
- ** in the [header pane](timeline::HeaderPaneWidget) and the display of the
+ ** in the [header pane](\ref timeline::HeaderPaneWidget) and the display of the
  ** timeline body, which is actually a canvas for custom drawing.
  ** 
  ** @todo WIP-WIP-WIP as of 12/2016
diff --git a/src/gui/ui-bus.cpp b/src/gui/ui-bus.cpp
index 999dcedce..d6c3233f7 100644
--- a/src/gui/ui-bus.cpp
+++ b/src/gui/ui-bus.cpp
@@ -25,9 +25,9 @@
 /** @file ui-bus.cpp
  ** Implementation of the UI backbone service for messaging.
  ** Any globally relevant widget or controller within the Lumiera UI
- ** is connected to the [UI-Bus](ui-bus.hpp), which is essentially implemented
+ ** is connected to the [UI-Bus](\ref ui-bus.hpp), which is essentially implemented
  ** within this compilation unit. [Clients](\ref gui::model::Tangible) typically
- ** use the [BusTerm-Interface](bus-term.hpp) to route generic actions and
+ ** use the [BusTerm-Interface](\ref bus-term.hpp) to route generic actions and
  ** receive notifications, state changes and mutations.
  ** 
  ** @see core-service.hpp
@@ -143,7 +143,7 @@ namespace ctrl {
     
     
     /** capture and record a "state mark" for later replay for restoring UI state.
-     * @param subject the [endpoint-ID](BusTerm::endpointID_) of the emitting element
+     * @param subject the [endpoint-ID](\ref BusTerm::endpointID_) of the emitting element
      * @param mark the actual state update or notification message to be remembered
      * @remarks relevant changes to presentation state, which are to be recalled and
      *          restored later, are emitted from the place they occur, packaged as
@@ -162,11 +162,11 @@ namespace ctrl {
     
     
     /** route a state update or notification to the given subject.
-     * @param subject the [endpoint-ID](BusTerm::endpointID_) of the element to address
+     * @param subject the [endpoint-ID](\ref BusTerm::endpointID_) of the element to address
      * @param mark the actual state update or notification message to be delivered
      * @remarks each addressed "subject" is a gui::model::Tangible, and as such holds
      *          a BusTerm of its own, which in turn ensures a registration and connection
-     *          from the [central routing hub](gui::ctrl::Nexus) down to the element. Thus,
+     *          from the [central routing hub](\ref gui::ctrl::Nexus) down to the element. Thus,
      *          the default implementation is just to pass the given state mark "up",
      *          assuming that it will reach the hub eventually, which in turn knows
      *          how to reach the element, and invoke the Tangible::mark() operation.
diff --git a/src/gui/ui-bus.hpp b/src/gui/ui-bus.hpp
index 6455b9cfb..d6788528d 100644
--- a/src/gui/ui-bus.hpp
+++ b/src/gui/ui-bus.hpp
@@ -64,11 +64,11 @@
  ** We distinguish between _up-link messages,_ directed towards some central service
  ** (presentation state management or command invocation) and _down-link messages,_
  ** directed towards individual elements. The interactions at the bus are closely interrelated
- ** with the [elementary UI-Element operations](tangible.hpp).
+ ** with the [elementary UI-Element operations](\ref tangible.hpp).
  ** 
  ** - *act*: send a [GenNode] representing the action
  **   - the ID is either a globally registered command-ID or an explicitly
- **     ["opened"](proc::control::SessionCommand::cycle(Symbol,string)) command instance ID.
+ **     ["opened"](\ref proc::control::SessionCommand::cycle(Symbol,string)) command instance ID.
  **   - the payload is a Record<GenNode> holding the actual command arguments
  **   - on reception, an _instance_ (anonymous clone copy) of the command is created, bound
  **     with the arguments and handed over to the ProcDispatcher to be enqueued for execution.
diff --git a/src/include/display-facade.h b/src/include/display-facade.h
index 270dc6172..82e9e846a 100644
--- a/src/include/display-facade.h
+++ b/src/include/display-facade.h
@@ -33,7 +33,7 @@
  **  by a better design, where rather the \em provider of an output facility
  **  registers with the OutputManager in the core.
  ** 
- ** @see [corresponding implementation](display-service.hpp)
+ ** @see [corresponding implementation](\ref display-service.hpp)
  ** @see gui::GuiFacade
  ** @see dummy-player-facade.h
  ** 
diff --git a/src/include/session-command-facade.h b/src/include/session-command-facade.h
index 5c1205e8d..ce49d9f28 100644
--- a/src/include/session-command-facade.h
+++ b/src/include/session-command-facade.h
@@ -75,7 +75,7 @@ namespace control {
    * 
    * The service exposed through this facade offers dedicated support for
    * the _standard command cycle_, as is typically performed from the UI.
-   * Such a usage cycle starts with ["opening"](#cycle) a local anonymous
+   * Such a usage cycle starts with ["opening"](\ref #cycle) a local anonymous
    * clone copy from the global command definition, which is then used
    * in further calls to be outfitted with actual arguments and finally
    * to be handed over to the dispatcher for execution.
@@ -87,7 +87,7 @@ namespace control {
    * use the embedded #facade factory, which yields a proxy to route any
    * calls through the lumieraorg_SessionCommand interface
    * @throws lumiera::error::State when interface is not opened
-   * @see [Command system](command.hpp)
+   * @see [Command system](\ref command.hpp)
    * @see SessionCommandFunction_test
    */
   class SessionCommand
diff --git a/src/lib/diff/list-diff.hpp b/src/lib/diff/list-diff.hpp
index 45e151e1b..3b90d61cc 100644
--- a/src/lib/diff/list-diff.hpp
+++ b/src/lib/diff/list-diff.hpp
@@ -23,7 +23,7 @@
 
 /** @file list-diff.hpp
  ** A token language to represent changes in a list of elements.
- ** In combination with the [DiffLanguage framework](diff-langue.hpp), this building
+ ** In combination with the [DiffLanguage framework](\ref diff-langue.hpp), this building
  ** block defines the set of operations to express changes in a given list of elements.
  ** By implementing the lib::diff::ListDiffInterpreter interface (visitor), a concrete
  ** usage can receive such a diff description and e.g. apply it to a target data structure.
diff --git a/src/lib/diff/mutation-message.hpp b/src/lib/diff/mutation-message.hpp
index 416bec91b..ff146cdac 100644
--- a/src/lib/diff/mutation-message.hpp
+++ b/src/lib/diff/mutation-message.hpp
@@ -256,7 +256,7 @@ namespace diff{
    * becomes the new generator and the old generator object is released,
    * since the assignment of the new backend typically removes the last
    * reference in the smart-ptr managing the generation backend. This
-   * process can be repeated and then the [diagnostics](operator string())
+   * process can be repeated and then the [diagnostics](\ref operator string())
    * will show the remainder of the sequence _left at that point._
    */
   inline MutationMessage&
diff --git a/src/lib/format-cout.hpp b/src/lib/format-cout.hpp
index 10840e1a1..3b7b65683 100644
--- a/src/lib/format-cout.hpp
+++ b/src/lib/format-cout.hpp
@@ -45,7 +45,7 @@
  ** @see FormatCOUT_test
  ** @see FormatHelper_test
  ** @see [generic string conversion helper](\ref util::toString() )
- ** @see [frontend for boost::format, printf-style](format-string.hpp)
+ ** @see [frontend for boost::format, printf-style](\ref format-string.hpp)
  ** 
  */
 
diff --git a/src/lib/format-obj.cpp b/src/lib/format-obj.cpp
index 9de89b7d4..b7eb0d26a 100644
--- a/src/lib/format-obj.cpp
+++ b/src/lib/format-obj.cpp
@@ -31,7 +31,7 @@
  ** investigate object contents and show types and addresses. They
  ** are referred from our [lightweight string converter](\ref
  ** util::StringConv), but also from the util::toString() function
- ** and more common [formatting utils](format-util.hpp).
+ ** and more common [formatting utils](\ref format-util.hpp).
  ** 
  ** @see FormatHelper_test
  ** @see FormatString_test
diff --git a/src/lib/format-obj.hpp b/src/lib/format-obj.hpp
index 562269e11..a4f7c8a87 100644
--- a/src/lib/format-obj.hpp
+++ b/src/lib/format-obj.hpp
@@ -38,7 +38,7 @@
  **         the way we did it for `boost::format`? This would reduce inclusion cost...
  ** 
  ** @see FormatHelper_test
- ** @see [frontend for boost::format, printf-style](format-string.hpp)
+ ** @see [frontend for boost::format, printf-style](\ref format-string.hpp)
  ** 
  */
 
diff --git a/src/lib/format-util.hpp b/src/lib/format-util.hpp
index eebf22638..3d926e9f5 100644
--- a/src/lib/format-util.hpp
+++ b/src/lib/format-util.hpp
@@ -30,7 +30,7 @@
  **         through our [generic string conversion](\ref util::toString)
  ** 
  ** @see FormatHelper_test
- ** @see [frontend for boost::format, printf-style](format-string.hpp)
+ ** @see [frontend for boost::format, printf-style](\ref format-string.hpp)
  ** 
  */
 
diff --git a/src/lib/iter-chain-search.hpp b/src/lib/iter-chain-search.hpp
index d8913318c..084a24851 100644
--- a/src/lib/iter-chain-search.hpp
+++ b/src/lib/iter-chain-search.hpp
@@ -68,7 +68,7 @@
  ** @see IterChainSearch_test
  ** @see IterCursor_test
  ** @see iter-tree-explorer.hpp
- ** @see [usage example](event-log.hpp)
+ ** @see [usage example](\ref event-log.hpp)
  ** 
  */
 
diff --git a/src/lib/iter-cursor.hpp b/src/lib/iter-cursor.hpp
index 259057956..013ed975e 100644
--- a/src/lib/iter-cursor.hpp
+++ b/src/lib/iter-cursor.hpp
@@ -26,12 +26,12 @@
  ** This wrapper relies on the ability of typical STL container iterators
  ** to work in both directions, similar to std::reverse_iterator.
  ** Yet it is a single, self-contained element and in compliance to the
- ** ["Lumiera Forward Iterator"](iter-adapter.hpp) concept. But it has
+ ** ["Lumiera Forward Iterator"](\ref iter-adapter.hpp) concept. But it has
  ** the additional ability to [switch the working direction](\ref IterCursor<IT>::switchDir).
  ** 
  ** @see IterCursor_test
  ** @see iter-adapter.hpp
- ** @see [usage example](event-log.hpp)
+ ** @see [usage example](\ref event-log.hpp)
  ** 
  */
 
@@ -156,7 +156,7 @@ namespace lib {
    * It can be built on top of any bidirectional STL iterator or similar entity,
    * which has an `--` operator. Initially, IterCursor will operate in forward
    * direction; irrespective of the current direction, it always fulfils the
-   * ["Lumiera Forward Iterator"](iter-adapter.hpp) concept, i.e. it can be
+   * ["Lumiera Forward Iterator"](\ref iter-adapter.hpp) concept, i.e. it can be
    * iterated until exhaustion, in which case it will evaluate to bool(false).
    * @note IterCursor instances can be equality compared, also taking the
    *       current direction into account. As a special case, all
diff --git a/src/lib/meta/trait.hpp b/src/lib/meta/trait.hpp
index d82364655..71b2d249b 100644
--- a/src/lib/meta/trait.hpp
+++ b/src/lib/meta/trait.hpp
@@ -39,10 +39,10 @@
  ** the ability for string conversions
  ** 
  ** \par ability to iterate
- ** these traits [can be used](util-foreach.hpp) to build the notion of a
+ ** these traits [can be used](\ref util-foreach.hpp) to build the notion of a
  ** generic container -- basically anything that can be enumerated.
  ** Within Lumiera, we frequently use our own concept of "iterability",
- ** known as ["Lumiera Forward Iterator"](iter-adapter.hpp). These
+ ** known as ["Lumiera Forward Iterator"](\ref iter-adapter.hpp). These
  ** helpers here allow to unify this concept with the "Range"
  ** concept from the standard library (`begin()` and `end()`)
  ** 
diff --git a/src/lib/meta/util.hpp b/src/lib/meta/util.hpp
index 5df0dad53..6a742c56a 100644
--- a/src/lib/meta/util.hpp
+++ b/src/lib/meta/util.hpp
@@ -334,7 +334,7 @@ namespace util {
    *    representation for pretty much every language object._ This minimal solution
    *    is defined here, to allow for built-in diagnostics for custom types without
    *    the danger of creating much header inclusion and code size bloat. A more
-   *    elaborate, [extended solution](lib::toString), including _lexical conversions
+   *    elaborate, [extended solution](\ref lib::toString), including _lexical conversions
    *    for numbers,_ is defined in format-obj.hpp
    * @note any exceptions during string conversion are caught and silently ignored;
    *    the returned string indicates "↯" in this case.
diff --git a/src/proc/control/command-instance-manager.hpp b/src/proc/control/command-instance-manager.hpp
index 1134d9d1b..7a7f3c478 100644
--- a/src/proc/control/command-instance-manager.hpp
+++ b/src/proc/control/command-instance-manager.hpp
@@ -88,7 +88,7 @@ namespace control {
    * #getInstance. It represents an _anonymous instance_ kept alive solely by the CommandInstanceManager
    * (i.e. there is no registration of a command under that instanceID in the global CommandRegistry).
    * When done with the parametrisation, by calling #dispatch, this anonymous instance will be handed
-   * over to the [Dispatcher](CommandDispatch) (installed on construction). Typically, this will in fact
+   * over to the [Dispatcher](\ref CommandDispatch) (installed on construction). Typically, this will in fact
    * be the proc::control::ProcDispatcher, which runs in a dedicated thread ("session loop thread") and
    * maintains a queue of commands to be dispatched towards the current session. Since Command is a smart
    * handle, the enqueued instance will stay alive until execution and then go out of scope. But, after
diff --git a/src/proc/control/command-setup.cpp b/src/proc/control/command-setup.cpp
index e592325e1..690eec058 100644
--- a/src/proc/control/command-setup.cpp
+++ b/src/proc/control/command-setup.cpp
@@ -295,8 +295,8 @@ namespace control {
    * opened instance, which will then be bound and dispatched likewise.
    * @param instanceID global commandID or previously opened local instanceID
    * @param argSeq command argument tuple packaged as Record<GenNode>, which
-   *               is the standard format [sent](BusTerm::act(GenNode)) for
-   *               command execution via [UI-bus](ui-bus.hpp)
+   *               is the standard format [sent](\ref BusTerm::act(GenNode)) for
+   *               command execution via [UI-bus](\ref ui-bus.hpp)
    */
   void
   CommandInstanceManager::bindAndDispatch (Symbol instanceID, Rec const& argSeq)
diff --git a/src/proc/control/command-setup.hpp b/src/proc/control/command-setup.hpp
index fedcf7871..251d665d9 100644
--- a/src/proc/control/command-setup.hpp
+++ b/src/proc/control/command-setup.hpp
@@ -24,7 +24,7 @@
 /** @file command-setup.hpp
  ** Provision for setup of concrete commands for use by the UI.
  ** A *Proc-Layer command* is a functor, which can be parametrised with actual arguments.
- ** It needs to be [defined](command-def.hpp) beforehand, which means to establish an unique
+ ** It needs to be [defined](\ref command-def.hpp) beforehand, which means to establish an unique
  ** name and to supply three functions, one for the actual command operation, one to capture
  ** state and one to _undo_ the effect of the command invocation. CommandSetup allows to create
  ** series of such definitions with minimal effort. Since any access and mutation from the UI into
diff --git a/src/proc/control/command.hpp b/src/proc/control/command.hpp
index 1a670785a..24b78c54e 100644
--- a/src/proc/control/command.hpp
+++ b/src/proc/control/command.hpp
@@ -37,8 +37,8 @@
  ** stored definition backend.
  ** 
  ** # Command definition, argument types and UNDO operation
- ** For a command to be usable at all, a concrete [command definition](command-def.hpp) need to be supplied
- ** somewhere in the code base. Typically this is done through static [command-setup bindings](command-setup.hpp).
+ ** For a command to be usable at all, a concrete [command definition](\ref command-def.hpp) need to be supplied
+ ** somewhere in the code base. Typically this is done through static [command-setup bindings](\ref command-setup.hpp).
  ** Such a command definition links three functions with the name-ID of the command
  ** - the actual command operation
  ** - a function to capture state
diff --git a/src/proc/control/media-impl-lib.hpp b/src/proc/control/media-impl-lib.hpp
index 08496ca30..d151d4954 100644
--- a/src/proc/control/media-impl-lib.hpp
+++ b/src/proc/control/media-impl-lib.hpp
@@ -24,7 +24,7 @@
 /** @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)
+ ** libraries. While configuring the render process, a [stream type](\ref 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,
diff --git a/src/proc/engine/dispatcher.hpp b/src/proc/engine/dispatcher.hpp
index 2b61ce5af..440037837 100644
--- a/src/proc/engine/dispatcher.hpp
+++ b/src/proc/engine/dispatcher.hpp
@@ -23,7 +23,7 @@
 
 /** @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)
+ ** On interface level, the render engine uses the notion of a [calculation stream](\ref 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.
diff --git a/tests/gui/abstract-tangible-test.cpp b/tests/gui/abstract-tangible-test.cpp
index 2aa65abd2..087c4b61e 100644
--- a/tests/gui/abstract-tangible-test.cpp
+++ b/tests/gui/abstract-tangible-test.cpp
@@ -197,7 +197,7 @@ namespace test {
        * the occurrence of expected events, invocations and responses.
        * 
        * ### connectivity
-       * Any mock element will automatically connect against the [Test-Nexus](test/test-nexus.hpp),
+       * Any mock element will automatically connect against the [Test-Nexus](\ref test/test-nexus.hpp),
        * so to be suitably rigged for unit testing. This means, there is no _live connection_
        * to the session, but any command- or other messages will be captured and can be
        * retrieved or verified from the test code. Since lifecycle and robustness in
diff --git a/tests/gui/bus-term-test.cpp b/tests/gui/bus-term-test.cpp
index a4a0153f5..1b5b91e28 100644
--- a/tests/gui/bus-term-test.cpp
+++ b/tests/gui/bus-term-test.cpp
@@ -112,7 +112,7 @@ namespace test {
   /**************************************************************************//**
    * @test cover the standard node element (terminal element) within the UI-Bus,
    * with the help of an attached mock UI element. Contrary to the related
-   * [ui-element test](AbstractTangible_test), here we focus on the bus side
+   * [ui-element test](\ref AbstractTangible_test), here we focus on the bus side
    * of the standard interactions.
    * 
    * This test enacts the fundamental generic communication patterns
@@ -150,7 +150,7 @@ namespace test {
       /** @test build a new BusTerm and verify connectivity.
        * Every [tangible UI-element](\ref Tangible) bears an embedded BusTerm
        * member. Since the latter _requires another, up-link BusTerm_ on construction,
-       * connection to the [UI-Bus](ui-bus.hpp) is structurally ensured. Moreover,
+       * connection to the [UI-Bus](\ref ui-bus.hpp) is structurally ensured. Moreover,
        * when hooking up a new UI-element, the initialisation of the embedded BusTerm
        * will cause a down-link connection to be installed into the central routing
        * table within the \ref Nexus, the hub of the UI-Bus. Routing and addressing
diff --git a/tests/gui/model/element-access-test.cpp b/tests/gui/model/element-access-test.cpp
index c87ad38a4..281aa98c5 100644
--- a/tests/gui/model/element-access-test.cpp
+++ b/tests/gui/model/element-access-test.cpp
@@ -79,7 +79,7 @@ namespace test {
    *       rather than on the real UI topology.
    * @see GenNodeLocationQuery
    * 
-   * @see [Mock testing support](test-element-access.hpp)
+   * @see [Mock testing support](\ref test-element-access.hpp)
    * @see id-scheme.hpp
    * @see ViewLocator
    * @see ViewSpecDSL_test
diff --git a/tests/gui/test/mock-elm.hpp b/tests/gui/test/mock-elm.hpp
index 132fe7ddc..82baec4b2 100644
--- a/tests/gui/test/mock-elm.hpp
+++ b/tests/gui/test/mock-elm.hpp
@@ -101,7 +101,7 @@ namespace test{
    * on the [Tangible] interface, which we mock here for unit testing.
    * This special implementation is instrumented to [log](\ref lib::test::EventLog)
    * any invocation and any messages sent or received through the UI Backbone,
-   * which is formed by the [UI-Bus](ui-bus.hpp).
+   * which is formed by the [UI-Bus](\ref ui-bus.hpp).
    * 
    * @todo some usage details
    * @see abstract-tangible-test.cpp
diff --git a/tests/gui/test/test-nexus.cpp b/tests/gui/test/test-nexus.cpp
index 5deb85cda..597cc3cd8 100644
--- a/tests/gui/test/test-nexus.cpp
+++ b/tests/gui/test/test-nexus.cpp
@@ -26,12 +26,12 @@
  ** This compilation unit provides the actual setup for running a faked
  ** user interface from unit tests. Test code is assumed to access those
  ** features through the [front-end](\ref gui::test::TestNexus), while the
- ** actual implementation instances are placed [as singletons](depend.hpp)
+ ** actual implementation instances are placed [as singletons](\ref depend.hpp)
  ** 
- ** This test setup will mostly treat messages similar to the [real UI-Bus hub](nexus.hpp),
+ ** This test setup will mostly treat messages similar to the [real UI-Bus hub](\ref nexus.hpp),
  ** with additional [logging](\ref event-log.hpp). Since the TestNexus runs as singleton,
- ** there is a single shared "nexus-log", which can be [accessed](test::Nexus::getLog) or
- ** even [cleared](test::Nexus::startNewLog) through the [static front-end](test::Nexus).
+ ** there is a single shared "nexus-log", which can be [accessed](\ref test::Nexus::getLog) or
+ ** even [cleared](\ref test::Nexus::startNewLog) through the [static front-end](\ref test::Nexus).
  ** But there is no connection to any [core services](\ref core-service.hpp), so neither
  ** commands nor state marks will be processed in any way. In case the unit tests need to
  ** integrate with or verify these handling operations, we provide the ability to install
@@ -420,7 +420,7 @@ namespace test{
   }
   
   /**
-   * similar to the [custom command handler](Nexus::setCommandHandler)
+   * similar to the [custom command handler](\ref Nexus::setCommandHandler)
    * this hook allows to install a closure to intercept any
    * "state mark" messages passed over the test-UI-Bus
    */
diff --git a/tests/gui/test/test-nexus.hpp b/tests/gui/test/test-nexus.hpp
index 73639ac6f..3cb9c8a15 100644
--- a/tests/gui/test/test-nexus.hpp
+++ b/tests/gui/test/test-nexus.hpp
@@ -23,7 +23,7 @@
 
 /** @file test/test-nexus.hpp
  ** A fake UI backbone for investigations and unit testing.
- ** Any relevant element within the Lumiera GTK UI is connected to the [UI-Bus](ui-bus.hpp)
+ ** Any relevant element within the Lumiera GTK UI is connected to the [UI-Bus](\ref ui-bus.hpp)
  ** So for testing and investigation we need a white room setup to provide an instrumented
  ** backbone to run any test probes against. The test::Nexus allows to [hook up](\ref testUI())
  ** a generic interface element, to participate in a simulated interface interaction.
@@ -64,7 +64,7 @@ namespace test{
   
   /**
    * Mock UI backbone for unit testing.
-   * In the absence of a real UI, this simulated [UI-Bus](ui-bus.hpp)
+   * In the absence of a real UI, this simulated [UI-Bus](\ref ui-bus.hpp)
    * can be used to wire a [test probe](\ref MockElm) and address it in unit testing.
    * 
    * @note behind the scenes, this is a singleton. Use the provided
diff --git a/tests/library/iter-chain-search-test.cpp b/tests/library/iter-chain-search-test.cpp
index e76aa14b8..714af1695 100644
--- a/tests/library/iter-chain-search-test.cpp
+++ b/tests/library/iter-chain-search-test.cpp
@@ -99,7 +99,7 @@ namespace test{
    * 
    * @see iter-chain-search.hpp
    * @see iter-cursor.hpp
-   * @see [usage example](event-log.hpp)
+   * @see [usage example](\ref event-log.hpp)
    */
   class IterChainSearch_test : public Test
     {
diff --git a/tests/library/iter-cursor-test.cpp b/tests/library/iter-cursor-test.cpp
index ef3b19195..b70f514d9 100644
--- a/tests/library/iter-cursor-test.cpp
+++ b/tests/library/iter-cursor-test.cpp
@@ -78,7 +78,7 @@ namespace test{
    *
    * @see iter-cursor.hpp
    * @see iter-adapter.hpp
-   * @see [usage example](event-log.hpp)
+   * @see [usage example](\ref event-log.hpp)
    */
   class IterCursor_test : public Test
     {