From 555af315b357d1872ccd5dba09884d6f74891bdf Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Sat, 26 Apr 2025 23:59:29 +0200 Subject: [PATCH] Upgrade: improve Doxygen parameters and treat some warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - remove obsolete configuration settings - walk through all settings according to the documentation https://www.doxygen.nl/manual/config.html - now try to use the new feature to rely on Clang for C++ parsing - walk through the doxygen-warnings.txt and fix some obvious misspellings and structural problems in the documentation comments. With Debian-Trixie, we are now using Doxygen 1.9.8 — which produces massively better results in various fine points. However, there are still problems with automatic cross links, especially from implementation to the corresponding test classes. --- doc/SConscript | 2 +- doc/devel/Doxyfile | 48 +++-- src/common/config-rules.hpp | 2 +- src/common/query.hpp | 6 +- src/doxygen.dox | 43 +++++ src/lib/cmdline.cpp | 2 +- src/lib/diff/tree-mutator.hpp | 4 +- src/lib/hash-combine.hpp | 2 +- src/lib/hetero-data.hpp | 6 +- src/lib/integral.hpp | 2 +- src/lib/iter-adapter-ptr-deref.hpp | 4 +- src/lib/iter-explorer.hpp | 2 +- src/lib/iter-source.hpp | 2 +- src/lib/luid.h | 6 +- src/lib/parse.hpp | 8 +- src/lib/polymorphic-value.hpp | 2 +- src/lib/scoped-holder-transfer.hpp | 8 +- src/lib/several-builder.hpp | 16 +- src/lib/simple-allocator.hpp | 4 +- src/lib/split-splice.hpp | 2 +- src/lib/stat/statistic.hpp | 2 +- src/lib/thread.cpp | 2 +- src/lib/time.h | 2 +- src/lib/util-tuple.hpp | 2 +- src/stage/config-keys.hpp | 4 +- src/stage/interact/ui-coord-resolver.hpp | 40 ++-- src/stage/interact/view-locator.hpp | 2 +- src/stage/interact/view-spec-dsl.hpp | 4 +- src/stage/timeline/body-canvas-widget.cpp | 2 +- src/steam/asset.cpp | 6 +- src/steam/asset.hpp | 2 +- src/steam/asset/media.hpp | 2 +- src/steam/asset/proc.hpp | 2 +- src/steam/assetmanager.hpp | 2 +- src/steam/control/argument-tuple-accept.hpp | 6 +- src/steam/control/steam-dispatcher.cpp | 2 +- src/steam/control/stypemanager.hpp | 2 +- src/steam/engine/engine-service.hpp | 2 +- src/steam/engine/feed-manifold.hpp | 2 +- src/steam/engine/node-builder.hpp | 4 +- src/steam/fixture/model-port-registry.cpp | 2 +- src/steam/fixture/model-port-registry.hpp | 2 +- src/steam/fixture/segment.hpp | 2 +- src/steam/fixture/segmentation.hpp | 2 +- src/steam/mobject/interpolator.hpp | 4 +- src/steam/mobject/model-port.hpp | 2 +- src/steam/mobject/output-mapping.hpp | 2 +- src/steam/mobject/session/effect.cpp | 2 +- src/steam/mobject/session/scope.hpp | 12 +- .../mobject/session/session-services.cpp | 2 +- src/steam/mobject/session/session.cpp | 4 +- src/vault/gear/activity-term.hpp | 2 +- src/vault/gear/block-flow.hpp | 2 +- tests/basics/typed-counter-test.cpp | 4 +- tests/basics/visitingtool-concept.cpp | 33 ++-- .../application/subsystem-runner-test.cpp | 2 +- ...est.cpp => output-proxy-provider-test.cpp} | 2 +- .../mobject/builder/builder-tool-test.cpp | 2 +- tests/library/hetero-data-test.cpp | 2 +- tests/library/index-iter-test.cpp | 2 +- tests/vault/gear/stress-test-rig.hpp | 2 +- wiki/thinkPad.ichthyo.mm | 178 ++++++++++++++---- 62 files changed, 338 insertions(+), 192 deletions(-) rename tests/core/steam/engine/{buffer-proxy-provider-test.cpp => output-proxy-provider-test.cpp} (98%) diff --git a/doc/SConscript b/doc/SConscript index e20bb4eb0..537b9b137 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -10,7 +10,7 @@ Import('env') doxydoc = env.Doxygen('devel/Doxyfile') # env.Install(dir = '$DESTDIR/share/doc/lumiera$VERSION/devel', source=documentation) -env.Clean (doxydoc, doxydoc + ['devel/,doxylog','devel/warnings.txt']) +env.Clean (doxydoc, doxydoc + ['devel/,doxylog','devel/doxygen-warnings.txt']) Export('doxydoc') diff --git a/doc/devel/Doxyfile b/doc/devel/Doxyfile index 89b27dc56..443965d1a 100644 --- a/doc/devel/Doxyfile +++ b/doc/devel/Doxyfile @@ -35,6 +35,7 @@ SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = NO INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 4 @@ -43,6 +44,7 @@ OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +MARKDOWN_ID_STYLE = GITHUB TOC_INCLUDE_HEADINGS = 2 AUTOLINK_SUPPORT = YES BUILTIN_STL_SUPPORT = YES @@ -55,17 +57,20 @@ INLINE_GROUPED_CLASSES = NO INLINE_SIMPLE_STRUCTS = YES TYPEDEF_HIDES_STRUCT = YES LOOKUP_CACHE_SIZE = 2 +NUM_PROC_THREADS = 0 +TIMESTAMP = DATE #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- -EXTRACT_ALL = NO +EXTRACT_ALL = YES EXTRACT_PRIVATE = YES EXTRACT_PACKAGE = YES EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = YES EXTRACT_ANON_NSPACES = YES +RESOLVE_UNNAMED_PARAMS = YES HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO @@ -73,12 +78,13 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = YES CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = YES +SHOW_HEADERFILE = YES SHOW_INCLUDE_FILES = YES SHOW_GROUPED_MEMB_INC = NO FORCE_LOCAL_INCLUDES = YES INLINE_INFO = YES SORT_MEMBER_DOCS = NO -SORT_BRIEF_DOCS = YES +SORT_BRIEF_DOCS = NO SORT_MEMBERS_CTORS_1ST = YES SORT_GROUP_NAMES = NO SORT_BY_SCOPE_NAME = NO @@ -150,15 +156,14 @@ REFERENCES_RELATION = YES REFERENCES_LINK_SOURCE = NO SOURCE_TOOLTIPS = YES USE_HTAGS = NO -VERBATIM_HEADERS = YES -CLANG_ASSISTED_PARSING = NO -CLANG_OPTIONS = +VERBATIM_HEADERS = NO +CLANG_ASSISTED_PARSING = YES +CLANG_OPTIONS = -DDEBUG -DEBUG_ALPHA #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 1 IGNORE_PREFIX = lumiera:: \ lumiera_ \ lumi_ \ @@ -175,11 +180,14 @@ HTML_FOOTER = HTML_STYLESHEET = HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = +HTML_COLORSTYLE = LIGHT HTML_COLORSTYLE_HUE = 344 HTML_COLORSTYLE_SAT = 68 HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = YES +HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = YES +HTML_CODE_FOLDING = YES +HTML_PROJECT_COOKIE = DoxyLumi HTML_INDEX_NUM_ENTRIES = 100 GENERATE_DOCSET = NO GENERATE_HTMLHELP = NO @@ -190,8 +198,8 @@ GENERATE_TREEVIEW = YES TREEVIEW_WIDTH = 200 ENUM_VALUES_PER_LINE = 1 EXT_LINKS_IN_WINDOW = NO +HTML_FORMULA_FORMAT = svg FORMULA_FONTSIZE = 9 -FORMULA_TRANSPARENT = YES USE_MATHJAX = NO SEARCHENGINE = YES SERVER_BASED_SEARCH = NO @@ -216,9 +224,7 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES LATEX_BATCHMODE = YES LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain -LATEX_TIMESTAMP = NO #--------------------------------------------------------------------------- # Configuration options related to the RTF output @@ -239,7 +245,7 @@ EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = -PREDEFINED = __cplusplus +PREDEFINED = __cplusplus DEBUG EBUG_ALPHA EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES @@ -251,41 +257,29 @@ GENERATE_TAGFILE = lumiera.tag ALLEXTERNALS = NO EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -PERL_PATH = /usr/bin/perl #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -CLASS_DIAGRAMS = YES -MSCGEN_PATH = -DIA_PATH = -HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES -DOT_NUM_THREADS = 0 -DOT_FONTNAME = FreeSans -DOT_FONTSIZE = 8 -DOT_FONTPATH = +DOT_NUM_THREADS = 0 # use all cores CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES +HIDE_UNDOC_RELATIONS = YES UML_LOOK = YES -UML_LIMIT_NUM_FIELDS = 8 +UML_LIMIT_NUM_FIELDS = 12 TEMPLATE_RELATIONS = YES INCLUDE_GRAPH = NO INCLUDED_BY_GRAPH = NO CALL_GRAPH = YES CALLER_GRAPH = YES -GRAPHICAL_HIERARCHY = NO DIRECTORY_GRAPH = YES +GRAPHICAL_HIERARCHY = NO DOT_IMAGE_FORMAT = svg INTERACTIVE_SVG = YES -DOT_PATH = -DOTFILE_DIRS = -MSCFILE_DIRS = -DIAFILE_DIRS = DOT_GRAPH_MAX_NODES = 80 MAX_DOT_GRAPH_DEPTH = 20 -DOT_TRANSPARENT = YES DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES DOT_CLEANUP = YES diff --git a/src/common/config-rules.hpp b/src/common/config-rules.hpp index 6bdbd1c08..1bbf9ecaf 100644 --- a/src/common/config-rules.hpp +++ b/src/common/config-rules.hpp @@ -160,7 +160,7 @@ namespace lumiera { * fulfilling the given query. * @param solution object fulfilling the query. Will be bound or * unified (in case it's already bound) with the first solution. - * @query any goals to be fulfilled by the solution. + * @param q any goals to be fulfilled by the solution. * @return false if resolution failed. In this case, solution ptr is empty. */ virtual bool resolve (P& solution, Query const& q) = 0; diff --git a/src/common/query.hpp b/src/common/query.hpp index 3847244a0..c34fd64c7 100644 --- a/src/common/query.hpp +++ b/src/common/query.hpp @@ -19,10 +19,10 @@ ** to decouple the parts of the application and allows for a rules based configuration and ** orchestration of the internal workings. ** - ** A Query is a request for just \em someone to come up with a solution, a preconfigured + ** A Query is a request for _just someone_ to come up with a solution, a preconfigured ** setup, some existing data object or contextual information. In order to be usable, ** actually a QueryResolver needs to be available to compute the solution and retrieve - ** the results. As a common denominator, queries can be generic queries given + ** the results. As a common denominator, queries can be _generic queries_ given ** in predicate logic syntax; in this case a generic query resolver (Planned feature ** as of 1/2013) will be able at least to determine a suitable facility for delegating ** the resolution. Besides, specific subsystems are using more specific kinds of @@ -45,7 +45,7 @@ ** The QueryResolver returns a result set, actually a Query::Cursor, which can be used to ** enumerate multiple solutions, if any. ** - ** Queries are \em immutable, but it is possible to re-build and remould a query using + ** Queries are _immutable_, but it is possible to re-build and remould a query using ** a Query::Builder, accessible via Query#build() and Query#rebuild(). ** ** @note as of 1/2013 this is rather a concept draft, but some parts of the code base diff --git a/src/doxygen.dox b/src/doxygen.dox index efd738f5c..984daff0e 100644 --- a/src/doxygen.dox +++ b/src/doxygen.dox @@ -107,3 +107,46 @@ implementation namespaces within \c lumiera:: Implementation namespace for support and library code. */ + + +/* ==== Test Namespaces ==== */ + +/** @namespace test +Test runner and basic definitions for tests. +*/ + +/** @namespace lib::test +Unit tests for the Lumiera support library. +*/ + +/** @namespace lib::test::test */ +/** @namespace lib::time::test */ +/** @namespace lib::diff::test */ +/** @namespace lib::hash::test */ +/** @namespace lib::idi::test */ +/** @namespace lib::iter::test */ +/** @namespace lib::meta::test */ + +/** @namespace util::test */ + +/** @namespace vault::test */ +/** @namespace vault::mem::test */ +/** @namespace vault::gear::test */ + +/** @namespace steam::test */ +/** @namespace steam::play:test */ +/** @namespace steam::engine::test */ +/** @namespace steam::fixture::test */ +/** @namespace steam::asset::test */ +/** @namespace steam::asset::meta::test */ +/** @namespace steam::control::test */ +/** @namespace steam::session::test */ +/** @namespace steam::builder::test */ + +/** @namespace stage::test */ +/** @namespace stage::ctrl::test */ +/** @namespace stage::model::test */ +/** @namespace stage::interact::test */ + +// Remark: for some unclear reason, cross-links to test-class names do not work in Doxygen; +// even after declaring these namespaces, or after setting EXTRACT_ALL = YES diff --git a/src/lib/cmdline.cpp b/src/lib/cmdline.cpp index a86e85728..2896fe231 100644 --- a/src/lib/cmdline.cpp +++ b/src/lib/cmdline.cpp @@ -36,7 +36,7 @@ using util::noneg; namespace lib { - /** create as a tokenised copy of the current commandline. + /** create as a tokenised _copy_ of the current commandline. * Note that argv[0] is always ignored. */ Cmdline::Cmdline (int argc, const char** argv) : vector (noneg(argc-1)) diff --git a/src/lib/diff/tree-mutator.hpp b/src/lib/diff/tree-mutator.hpp index 7124691b1..f889a3f5f 100644 --- a/src/lib/diff/tree-mutator.hpp +++ b/src/lib/diff/tree-mutator.hpp @@ -430,7 +430,7 @@ namespace diff{ auto ignoreAllChanges(); - /** attach a listener function, to be invoked on _structural changes._ + /** attach a listener function, to be invoked on _structural changes_. * Here, we define any change as "structural", which alters the _sequence_ of * child elements, as opposed to their content. In practice, this listener will * be invoked _after_ applying a diff with any `INS`, `DEL`, `FIND`, `SKIP` verb. @@ -442,7 +442,7 @@ namespace diff{ template auto onSeqChange (LIS changeListener); - /** attach a listener function, to be invoked on any _local change._ + /** attach a listener function, to be invoked on any _local change_. * This includes the [structural changes](\ref onSeqChange()), but also * value assignments to any attribute or element. * @note mutation of a nested child scope will _not_ trigger this listener. diff --git a/src/lib/hash-combine.hpp b/src/lib/hash-combine.hpp index 90bb34ea5..f008f979c 100644 --- a/src/lib/hash-combine.hpp +++ b/src/lib/hash-combine.hpp @@ -28,7 +28,7 @@ */ -/** @file hash-combine.h +/** @file hash-combine.hpp ** Hash combine function extracted from LibBoost 1.67 ** Combine two hash values to form a composite depending on both. ** @todo 2024 the Lumiera project has yet to decide how to approach diff --git a/src/lib/hetero-data.hpp b/src/lib/hetero-data.hpp index 046faeae3..36cc5ed79 100644 --- a/src/lib/hetero-data.hpp +++ b/src/lib/hetero-data.hpp @@ -31,6 +31,7 @@ ** ** # Usage ** @warning it is essential to understand where actual storage resides! + ** ** A HeteroData chain is built-up gradually, starting with a front-block ** - the front-block is usually placed at an _anchor location_ and populated with data ** - retrieve a _chain constructor type_ from the _type_ of the front-block, @@ -39,7 +40,8 @@ ** - need to link this data block explicitly into the front ** - get _accessor types_ from the _chain constructor_ ** - use these to work with individual data elements _through the front-block._ - ** @example + ** + **\par example of typical usage ** \code ** using Front = lib::HeteroData; ** auto h1 = Front::build (1,2.3); @@ -205,7 +207,7 @@ namespace lib { /** - * Accessor-functor to get at the data residing within some tuple element + * Accessor-functor to get at the data residing within some tuple element. * Using the enclosing typed scope to ensure safe storage access * @tparam slot number of the data element, counting from zero over the full chain * @note this functor holds no data, but shall be applied to some existing HeteroData. diff --git a/src/lib/integral.hpp b/src/lib/integral.hpp index c77e1cc26..b9d34c6b7 100644 --- a/src/lib/integral.hpp +++ b/src/lib/integral.hpp @@ -12,7 +12,7 @@ */ -/** @file integral.h +/** @file integral.hpp ** Inclusion for common place integral types and constants. */ diff --git a/src/lib/iter-adapter-ptr-deref.hpp b/src/lib/iter-adapter-ptr-deref.hpp index 3f87cbb5a..e1aee69b0 100644 --- a/src/lib/iter-adapter-ptr-deref.hpp +++ b/src/lib/iter-adapter-ptr-deref.hpp @@ -103,8 +103,8 @@ namespace lib { * from (TY *)* -- just we know that our intention is to dereference both levels * of pointers, and then the resulting conversion is correct. * @note in case IT == WrappedIterType, this is just a redefinition of the - * default copy ctor. In all other cases, this is an additional - * ctor besides the default copy ctor */ + * default copy ctor. In all other cases, this is an _additional + * ctor besides the default copy ctor_. */ PtrDerefIter (PtrDerefIter const& oIter) : i_(reinterpret_cast (oIter.getBase())) { } diff --git a/src/lib/iter-explorer.hpp b/src/lib/iter-explorer.hpp index 7733480b3..e09ddad28 100644 --- a/src/lib/iter-explorer.hpp +++ b/src/lib/iter-explorer.hpp @@ -1877,7 +1877,7 @@ namespace lib { - /** builder function to attach a _custom extension layer._ + /** builder function to attach a _custom extension layer_. * Any template in compliance with the general construction scheme can be injected through the template parameter. * - it must take a first template parameter SRC and inherit from this source iterator * - towards layers on top, it must behave like a _state core,_ either by redefining the state core API functions, diff --git a/src/lib/iter-source.hpp b/src/lib/iter-source.hpp index 69bb18e88..30d6b1f9b 100644 --- a/src/lib/iter-source.hpp +++ b/src/lib/iter-source.hpp @@ -13,7 +13,7 @@ /** @file iter-source.hpp ** Extension module to build an opaque data source, accessible as - ** Lumiera Forward Iterator. It is based on combining an IterAdapter + ** **Lumiera Forward Iterator**. It is based on combining an IterAdapter ** with classical polymorphism; here, the data source, which is addressed ** by IderAdapter through the "iteration control API", is abstracted behind ** an interface (with virtual functions). Together this allows to build diff --git a/src/lib/luid.h b/src/lib/luid.h index 913effae9..3fae6be0b 100644 --- a/src/lib/luid.h +++ b/src/lib/luid.h @@ -20,14 +20,14 @@ ** Due to the extremely huge number space, LUID values can be used as unique identifiers ** without the need to check for duplicates or collisions. At various places, LUIDs are ** thus used right away on creation of new object instances or elements, in case a - ** distinguishable object identity is required, e.g. + ** distinguishable _object identity_ is required, e.g. ** - any new attachment of an object into the session ("placement") ** - unique output designation discovered during the translation into a low-level ** node graph ("builder") ** - interface slots for external binding and plug-ins ** - ** Moreover, there is a \link luidgen.c Luidgen \endlink tool to generate fixed LUIDs - ** to be included into source code. It works by replacing the token \c LUIDGEN in the + ** Moreover, there is a [Luidgen](\ref luidgen.c) tool to generate fixed LUIDs + ** to be included into source code. It works by replacing the token `LUIDGEN` in the ** source code text by a newly generated (random) LUID in octal representation. ** ** LUIDs can also be used to generate hash values for hash table storage. diff --git a/src/lib/parse.hpp b/src/lib/parse.hpp index 83c734cd2..fc3a5fd1c 100644 --- a/src/lib/parse.hpp +++ b/src/lib/parse.hpp @@ -232,7 +232,7 @@ namespace util { /** - * Foundation: build a \ref Connex to accept a _terminal symbol._ + * Foundation: build a \ref Connex to accept a _terminal symbol_. * the actual parsing is delegated to a Regular Expression, * which must match against the _beginning_ of the input sequence, * possibly after skipping some whitespace. The defined parser @@ -966,8 +966,8 @@ namespace util { } /** - * Start Syntax with a sub-clause enclosed into a _bracketing construct._ - * The »bracket« is defined as syntax for the _open marker_ and _close marker._ + * Start Syntax with a sub-clause enclosed into a _bracketing construct_. + * The »bracket« is defined as syntax for the _open marker_ and _close marker_. * These are consumed without generating model elements. The parse fails unless * the full sequence `open body close` can be matched. */ @@ -1061,7 +1061,7 @@ namespace util { /** * Combinator: extend this Syntax clause by expecting a further sub-clause * behind the part of the input matched by the already defined part of this Syntax. - * The result model will be a \SeqModel, which essentially is a tuple of the + * The result model will be a \ref SeqModel, which essentially is a tuple of the * result models of all sequenced parts. * @return Syntax clause instance accepting the extended structure. * @warning the old syntax is invalidated by moving the parse-function out. diff --git a/src/lib/polymorphic-value.hpp b/src/lib/polymorphic-value.hpp index 1e31bf176..54cafe04a 100644 --- a/src/lib/polymorphic-value.hpp +++ b/src/lib/polymorphic-value.hpp @@ -38,7 +38,7 @@ ** just for passing an abstraction barrier (while the optimiser can be expected to ** remove this barrier and the accompanying nominal copy operations altogether in ** the generated code). Consequently the ability to return a polymorphic object - ** from a factory or configuration function by value would open a lot of + ** from a factory or configuration function _by value_ would open a lot of ** straight forward design possibilities and concise formulations. ** ** # how to build a copyable value without knowing it's layout in detail diff --git a/src/lib/scoped-holder-transfer.hpp b/src/lib/scoped-holder-transfer.hpp index 36e0391f7..0f6a130a6 100644 --- a/src/lib/scoped-holder-transfer.hpp +++ b/src/lib/scoped-holder-transfer.hpp @@ -54,13 +54,13 @@ namespace lib { * two instances, it will invoke a free function named * transfer_control(TY& from, TY& to) intended * to be found by ADL. Note: in case this function throws, - * it must not have any side effects. - * - besides, the \em noncopyable type needs to provide an + * it **must not have any side effects**. + * - besides, the _noncopyable_ type needs to provide an * operator bool() yielding true iff currently * containing an managed object. This is similar to * std::unique_ptr or even the behaviour of a plain - * old raw pointer, which is equivalent to \c true - * when the pointer isn'T \c NULL + * old raw pointer, which is equivalent to `true` + * when the pointer isn'T `NULL` * @deprecated obsoleted by C++11 rvalue references * */ diff --git a/src/lib/several-builder.hpp b/src/lib/several-builder.hpp index deb45add4..146f94c3d 100644 --- a/src/lib/several-builder.hpp +++ b/src/lib/several-builder.hpp @@ -20,10 +20,10 @@ ** ** # Implementation data layout ** - ** The front-end container lib::Several is actually just a smart-ptr referring + ** The front-end container `lib::Several` is actually just a smart-ptr referring ** to the actual data storage, which resides within an _array bucket._ Typically ** the latter is placed into memory managed by a custom allocator, most notably - ** lib::AllocationCluster. However, by default, the ArrayBucket will be placed + ** lib::AllocationCluster. However, by default, the `ArrayBucket` will be placed ** into heap memory. All further meta information is also maintained alongside ** this data allocation, including a _deleter function_ to invoke all element ** destructors and de-allocate the bucket itself. Neither the type of the @@ -31,7 +31,7 @@ ** ** Since the actual data elements can (optionally) be of a different type than ** the exposed interface type \a I, additional storage and spacing is required - ** in the element array. The field ArrayBucket::spread defines this spacing + ** in the element array. The field `ArrayBucket::spread` defines this spacing ** and thus the offset used for subscript access. The actual data storage starts ** immediately behind the ArrayBucket, which thus acts as a metadata header. ** This arrangement requires a sufficiently sized raw memory allocation to place @@ -144,7 +144,7 @@ namespace lib { /** * Helper to determine the »spread« required to hold - * elements of type \a TY in memory _with proper alignment._ + * elements of type \a TY in memory _with proper alignment_. */ template size_t inline constexpr @@ -170,7 +170,7 @@ namespace lib { namespace allo {// Allocation management policies /** - * Generic factory to manage objects within an ArrayBucket storage, + * Generic factory to manage objects within an `ArrayBucket` storage, * delegating to a custom allocator \a ALO for memory handling. * - #create a storage block for a number of objects * - #createAt construct a single payload object at index position @@ -291,7 +291,7 @@ namespace lib { /** * Policy Mix-In used to adapt to the ElementFactory and Allocator. - * @tparam I Interface type (also used in the lib::Several front-end + * @tparam I Interface type (also used in the `lib::Several` front-end * @tparam E a common _element type_ to use by default * @tparam ALO custom allocator template */ @@ -369,7 +369,7 @@ namespace lib { /*************************************************//** - * Builder to create and populate a lib::Several. + * Builder to create and populate a `lib::Several`. * Content elements can be of the _interface type_ \a I, * or the _default element type_ \a E. When possible, even * elements of an ad-hoc given, unrelated type can be used. @@ -388,7 +388,7 @@ namespace lib { * patterns, consistency checks may throw at runtime, * when attempting to add an unsuitable element. */ - template + template` ,class E =I ///< a subclass element element type (relevant when not trivially movable and destructible) ,template class POL =allo::HeapOwn ///< Allocator policy template (parametrised `POL`) > diff --git a/src/lib/simple-allocator.hpp b/src/lib/simple-allocator.hpp index 150facd0a..45fa8969c 100644 --- a/src/lib/simple-allocator.hpp +++ b/src/lib/simple-allocator.hpp @@ -61,8 +61,8 @@ namespace lib { /** * Policy: use just plain heap allocations - * @waring whenever you define a specialisation, - * _you_ are responsible for proper alignment + * @warning whenever you define a specialisation, + * _you_ are responsible for proper alignment * @see TICKET #1204 */ template diff --git a/src/lib/split-splice.hpp b/src/lib/split-splice.hpp index 4bb88f03a..02add3a17 100644 --- a/src/lib/split-splice.hpp +++ b/src/lib/split-splice.hpp @@ -12,7 +12,7 @@ */ -/** @file splite-splice.hpp +/** @file split-splice.hpp ** Generic algorithm to splice a new segment into a seamless segmentation of intervals. ** Here _"segmentation"_ denotes a partitioning of an ordered axis into a seamless sequence ** of intervals (here called "segment"). The axis is based on some _ordering type,_ like e.g. diff --git a/src/lib/stat/statistic.hpp b/src/lib/stat/statistic.hpp index 88aa0ee27..c4326938f 100644 --- a/src/lib/stat/statistic.hpp +++ b/src/lib/stat/statistic.hpp @@ -12,7 +12,7 @@ */ -/** @file statistic.cpp +/** @file statistic.hpp ** Support for generic statistics calculations. ** - average over the N last elements in a data sequence ** - simple linear regression with weights (single predictor variable) diff --git a/src/lib/thread.cpp b/src/lib/thread.cpp index a202b362d..0f227f21e 100644 --- a/src/lib/thread.cpp +++ b/src/lib/thread.cpp @@ -11,7 +11,7 @@ * *****************************************************************/ -/** @file sync.cpp +/** @file thread.cpp ** This compilation unit holds some implementation details ** of the [thread wrapper](\ref lib::Thread), relegated here ** to reduce header inclusions. diff --git a/src/lib/time.h b/src/lib/time.h index 4fc96952a..3f1931738 100644 --- a/src/lib/time.h +++ b/src/lib/time.h @@ -102,7 +102,7 @@ int64_t lumiera_quantise_frames_fps (gavl_time_t time, gavl_time_t origin, uint framerate); /** - * Similar to #lumiera_quantise_frames, but returns a grid aligned _relative time._ + * Similar to #lumiera_quantise_frames, but returns a grid aligned _relative time_. * @return time of start of the grid interval containing the given time, * but measured relative to the origin * @warning because the resulting value needs to be limited to fit into a 64bit long, diff --git a/src/lib/util-tuple.hpp b/src/lib/util-tuple.hpp index 5f3c46215..1dd87d07c 100644 --- a/src/lib/util-tuple.hpp +++ b/src/lib/util-tuple.hpp @@ -12,7 +12,7 @@ */ -/** @file util-tuples.hpp +/** @file util-tuple.hpp ** Some small helpers and convenience shortcuts to simplify working with ** tuples and sequences (given by iterator). While tuples and sequences ** are fundamentally different insofar a tuple has a fixed structure (and diff --git a/src/stage/config-keys.hpp b/src/stage/config-keys.hpp index a4da9df9c..e4902d34b 100644 --- a/src/stage/config-keys.hpp +++ b/src/stage/config-keys.hpp @@ -21,8 +21,8 @@ ** The UI layer retrieves the necessary configuration values from lumiera::Config, ** the config facade in the application core. Currently as of 2/2011 these values are ** loaded from setup.ini, because the full-blown config system is not yet implemented. - ** Amongst others, this configuration defines a search path for icons and a - ** separate search path for resources. These path specs may use the token \c $ORIGIN + ** Amongst others, this configuration defines a _search path_ for icons and a + ** separate search path for resources. These path specs may use the token `$ORIGIN` ** to refer to the installation directory of the currently executing program. ** This allows for a relocatable Lumiera installation bundle. ** diff --git a/src/stage/interact/ui-coord-resolver.hpp b/src/stage/interact/ui-coord-resolver.hpp index ce7729675..3525dcc16 100644 --- a/src/stage/interact/ui-coord-resolver.hpp +++ b/src/stage/interact/ui-coord-resolver.hpp @@ -54,20 +54,20 @@ ** and the presence of some component, several contextual predications may be queried: ** ** - *anchorage* - ** ** the way the given coordinate spec is or can be anchored - ** *** it is already _explicitly anchored_ by referring either to a specific window or by generic specification - ** *** it _can be a anchored_ by interpolation of some wildcards - ** *** it is _incomplete_ and need to be extended to allow anchoring - ** *** it is _impossible to anchor_ in the current UI configuration + ** + the way the given coordinate spec is or can be anchored + ** * it is already _explicitly anchored_ by referring either to a specific window or by generic specification + ** * it _can be a anchored_ by interpolation of some wildcards + ** * it is _incomplete_ and need to be extended to allow anchoring + ** * it is _impossible to anchor_ in the current UI configuration ** ** - *coverage* - ** ** the extent to which a given coordinate spec is backed by the actual UI configuration - ** ** _please note_: to determine the coverage, the spec needs to be anchored, either explicitly, - ** or by interpolation, or by extension of an incomplete spec - ** *** it is _completely covered_ - ** *** it is _partially covered_ with an remaining, uncovered extension part - ** *** it is _possible to cover completely_ - ** *** it is _impossible to cover_ related to the current UI topology + ** + the extent to which a given coordinate spec is backed by the actual UI configuration + ** + _please note_: to determine the coverage, the spec needs to be anchored, either explicitly, + ** or by interpolation, or by extension of an incomplete spec + ** * it is _completely covered_ + ** * it is _partially covered_ with an remaining, uncovered extension part + ** * it is _possible to cover completely_ + ** * it is _impossible to cover_ related to the current UI topology ** ** \par Some fine points to note ** Anchorage and coverage are not the same thing, but coverage implies anchorage. Only when a path is complete @@ -84,17 +84,17 @@ ** it is also possible to rewrite or extend the spec based on this environment ** ** - *anchoring* - ** ** in correspondence to the possible states of anchorage, we may derive an explicitly anchored spec - ** *** by interpolating the given spec - ** *** by interpretation and extension of the given spec + ** + in correspondence to the possible states of anchorage, we may derive an explicitly anchored spec + ** * by interpolating the given spec + ** * by interpretation and extension of the given spec ** ** - *covering* - ** ** we may construct the covered part of a given spec, which includes automatic anchoring + ** + we may construct the covered part of a given spec, which includes automatic anchoring ** ** - *extending* - ** ** a given UI coordinate pattern is covered... - ** ** and _truncated_ to the covered part - ** ** the given _extension suffix_ is then attached behind + ** + a given UI coordinate pattern is covered... + ** + and _truncated_ to the covered part + ** + the given _extension suffix_ is then attached behind ** ** @see UICoordResolver_test ** @see UICoord_test @@ -536,7 +536,7 @@ namespace interact { } - /** mutate to turn a wildcard into _existentially quantified._ + /** mutate to turn a wildcard into _existentially quantified_. * This means to assume (or require) that an element actually exists at the given position, * without knowing or caring about its actual name. This becomes relevant when matching for * _partially covered_ path; normal wildcards are only accepted to build a solution, when diff --git a/src/stage/interact/view-locator.hpp b/src/stage/interact/view-locator.hpp index 0ac4d09a7..9835a1017 100644 --- a/src/stage/interact/view-locator.hpp +++ b/src/stage/interact/view-locator.hpp @@ -15,7 +15,7 @@ /** @file view-locator.hpp ** Access and allocation of UI component views. ** Within the Lumiera UI, a _component view_ is a building block to deal with some component - ** of relevance to _»the model«. As such, all component views exhibit some distinctive traits: + ** of relevance to _»the model«_. As such, all component views exhibit some distinctive traits: ** - they conform to a built-in fixed list of view types, each of which is unique and dedicated ** to a very specific purpose: *Timeline*, *Viewer*, (Asset)*Bin*, *Infobox*, *Playcontrol*,... ** - each component view has a distinguishable identity and is connected to and addressable diff --git a/src/stage/interact/view-spec-dsl.hpp b/src/stage/interact/view-spec-dsl.hpp index 68d99f714..de7eb0c0b 100644 --- a/src/stage/interact/view-spec-dsl.hpp +++ b/src/stage/interact/view-spec-dsl.hpp @@ -169,8 +169,8 @@ namespace interact { /** - * Allocator is a functor to resolve a given, desired location of a view within the UI, resulting - * in creation or allocation of the view -- which happens _as side-effect._ The result of this invocation + * Allocator is a functor to resolve a given, desired location of a view within the UI. Invocation results + * in creation or allocation of the view -- which happens _as side-effect_. The result of this invocation * are the UI coordinates of an existing or newly created view. */ using Allocator = std::function; diff --git a/src/stage/timeline/body-canvas-widget.cpp b/src/stage/timeline/body-canvas-widget.cpp index 7f0df4d2a..906a725a1 100644 --- a/src/stage/timeline/body-canvas-widget.cpp +++ b/src/stage/timeline/body-canvas-widget.cpp @@ -490,7 +490,7 @@ namespace timeline { /** * The Lumiera Timeline model does not rely on a list of tracks, as most conventional video editing software does -- - * rather, each sequence holds a _fork of nested scopes._ This recursively nested structure is parallelled in the way + * rather, each sequence holds a _fork of nested scopes_. This recursively nested structure is parallelled in the way * we organise and draw the timeline representation onto the TimelineCanvas: we use an intermediary entity, the TrackBody * as an organisational grouping device, even while we draw _all of the timeline representation_ onto a single global * #mainCanvas_ within the (scrollable) #contentArea_. Thus, adding the first TrackBody to represent the root track diff --git a/src/steam/asset.cpp b/src/steam/asset.cpp index f644ac43e..25e7bac51 100644 --- a/src/steam/asset.cpp +++ b/src/steam/asset.cpp @@ -152,9 +152,9 @@ namespace asset { other->unlink (this->id); } - /** release all links to other dependent - * asset objects held internally and advise all parent - * assets to do so with the link to this asset. + /** release all links to other _dependent asset objects_ + * held internally and advise all parent assets to do so + * with the link to this asset. * @note we don't release upward links to parent assets, * thus effectively keeping the parents alive, because * frequently the accessibility of parent assets is part diff --git a/src/steam/asset.hpp b/src/steam/asset.hpp index 5d93f978c..1a6df51db 100644 --- a/src/steam/asset.hpp +++ b/src/steam/asset.hpp @@ -21,7 +21,7 @@ ** These classes are placed into namespace asset and proc_interface. ** ** Assets are handled by a hierarchy of interfaces. Below the top level Asset interface - ** there are interfaces for various different Kinds of Assets, like asset::Media, + ** there are interfaces for various different _Kinds of Assets_, like asset::Media, ** asset::Proc, etc. Code utilising the specific properties of e.g. Media assets, will ** be implemented directly against the asset::Media interface. To make this feasible ** while at the same time being able to handle all asset Kinds in a uniform manner, diff --git a/src/steam/asset/media.hpp b/src/steam/asset/media.hpp index eebc0ec77..e01f9f3a8 100644 --- a/src/steam/asset/media.hpp +++ b/src/steam/asset/media.hpp @@ -14,7 +14,7 @@ /** @file media.hpp ** Media data represented a specific kind of Asset. - ** For the different kinds of Assets, we use sub-interfaces inheriting + ** For the different _kinds of Assets_, we use sub-interfaces inheriting ** from the general Asset interface. To be able to get asset::Media instances ** directly from the AssetManager, we define a specialisation of the Asset ID. ** diff --git a/src/steam/asset/proc.hpp b/src/steam/asset/proc.hpp index de971672a..cb6735957 100644 --- a/src/steam/asset/proc.hpp +++ b/src/steam/asset/proc.hpp @@ -14,7 +14,7 @@ /** @file proc.hpp ** Data processing Plugins and Codecs can be treated as a specific Kind of Asset. - ** For the different Kinds of Assets, we use sub-interfaces inheriting + ** For the different _Kinds of Assets_, we use sub-interfaces inheriting ** from the general Asset interface. To be able to get asset::Proc instances ** directly from the AssetManager, we define a specialisation of the Asset ID. ** diff --git a/src/steam/assetmanager.hpp b/src/steam/assetmanager.hpp index 4c450e8e3..9e6ed8047 100644 --- a/src/steam/assetmanager.hpp +++ b/src/steam/assetmanager.hpp @@ -93,7 +93,7 @@ namespace asset { bool known (IDA id, const Category& cat) ; /** remove the given asset from the internal DB. - * together with all its dependents */ + * _together with all its dependents_. */ void remove (IDA id) ; /** deregister and evict all known Assets. diff --git a/src/steam/control/argument-tuple-accept.hpp b/src/steam/control/argument-tuple-accept.hpp index 55680cdc7..02be84b29 100644 --- a/src/steam/control/argument-tuple-accept.hpp +++ b/src/steam/control/argument-tuple-accept.hpp @@ -541,8 +541,8 @@ namespace control { /** Helper Template for building a Functor or function-like class: * Mix in a function call operator, which mimics the specified signature SIG . * This template is to be used as a base class to inherit the target type TAR from; - * this target type is assumed to provide a function \bindArg(Tuple) -- - * where \c TYPES... is the sequence of types found in the provided Signature SIG. + * this target type is assumed to provide a function `bindArg(Tuple)` — + * where `TYPES...` is the sequence of types found in the provided Signature \a SIG. */ template class AcceptArgumentTuple @@ -551,7 +551,7 @@ namespace control { { }; - /** Helper Template for Steam-Layer control::Command : mix in a \c bind(...) function + /** Helper Template for Steam-Layer control::Command : mix in a `bind(...)` function * @param SIG function signature to mimic (regarding the arguments and return type) * @param TAR the target class providing a function \c bindArg(Tuple >) * @param BASE the base class for inheritance chaining diff --git a/src/steam/control/steam-dispatcher.cpp b/src/steam/control/steam-dispatcher.cpp index abe38bea7..d7c951331 100644 --- a/src/steam/control/steam-dispatcher.cpp +++ b/src/steam/control/steam-dispatcher.cpp @@ -101,7 +101,7 @@ namespace control { /********************************************************************//** - * PImpl within SteamDispatcher to implement the _Session Loop Thread._ + * PImpl within SteamDispatcher to implement the _Session Loop Thread_. * During the lifetime of this object... * - the SessionCommandService is offered to enqueue commands * - the Session Loop thread dispatches commands and triggers the Builder diff --git a/src/steam/control/stypemanager.hpp b/src/steam/control/stypemanager.hpp index 7a7a854de..056ac3a7c 100644 --- a/src/steam/control/stypemanager.hpp +++ b/src/steam/control/stypemanager.hpp @@ -80,7 +80,7 @@ namespace control { friend class lib::DependencyFactory; /** Lifecycle: reset all type registration information - * to the generic pristine default state. This includes + * to the _generic pristine default_ state. This includes * hard wired defaults and defaults provided by type plugins, but * excludes everything added by the session */ diff --git a/src/steam/engine/engine-service.hpp b/src/steam/engine/engine-service.hpp index 7d752f568..6f1167eb2 100644 --- a/src/steam/engine/engine-service.hpp +++ b/src/steam/engine/engine-service.hpp @@ -18,7 +18,7 @@ ** The EngineService singleton has no state beyond the jobs currently managed by the ** scheduler; when the latter isn't available, any invocation will throw. ** - ** The central concept provided through this facade interface is the calculation stream. + ** The central concept provided through this facade interface is the **calculation stream**. ** This represents a series of calculations, expected to happen in a timely fashion and in order ** to deliver a frame data stream into an opened output connection. On the implementation side, ** a calculation stream will be translated into a series of jobs to invoke render nodes; diff --git a/src/steam/engine/feed-manifold.hpp b/src/steam/engine/feed-manifold.hpp index c1e099507..3d9b7c72d 100644 --- a/src/steam/engine/feed-manifold.hpp +++ b/src/steam/engine/feed-manifold.hpp @@ -236,7 +236,7 @@ namespace engine { /** - * Trait template to handle an _associated parameter functor._ + * Trait template to handle an _associated parameter functor_. * In those cases, where the basic processing function is classified such * as to accept parameter(s), it may be desirable to _generate_ those parameters * at invocation — be it as a fixed parametrisation chosen for this usage, or even diff --git a/src/steam/engine/node-builder.hpp b/src/steam/engine/node-builder.hpp index 29fdf5b1e..aaa041a86 100644 --- a/src/steam/engine/node-builder.hpp +++ b/src/steam/engine/node-builder.hpp @@ -77,7 +77,7 @@ ** ** ## Flavours of the processing function ** The binding to the actual data processing operations (usually supplied by an external library) - ** is established by a **processing-functor** passed to configure the [Port builder](\PortBuilderRoot::invoke()). + ** is established by a **processing-functor** passed to configure the [Port builder](\ref PortBuilderRoot::invoke()). ** The supported signatures of this functor are quite flexible to allow for various flavours of invocation. ** Data types of parameters and buffers are picked up automatically (at compile time), based on the ** signature of the actual function supplied. The accepted variations are described in detail @@ -603,7 +603,7 @@ namespace engine { /** - * Nested sub-Builder analogous to \ref PortBuilder, but for building a _»Param Agent Node«._ + * Nested sub-Builder analogous to \ref PortBuilder, but for building a _»Param Agent Node«_. * This will compute additional parameters and make them temporarily accessible through the * TurnoutSystem of the invocation, but only while delegating recursively to another * computation node, which can then draw upon these additional parameter values. diff --git a/src/steam/fixture/model-port-registry.cpp b/src/steam/fixture/model-port-registry.cpp index 82bcb660f..efe8c0294 100644 --- a/src/steam/fixture/model-port-registry.cpp +++ b/src/steam/fixture/model-port-registry.cpp @@ -99,7 +99,7 @@ namespace fixture { - /** does the transaction currently being built + /** does the transaction _currently being built_ * already contain a model port registration for the given ID? * @note this does \em not query registration state of the * global registry; use #isRegistered for that...*/ diff --git a/src/steam/fixture/model-port-registry.hpp b/src/steam/fixture/model-port-registry.hpp index 02d1bf06e..62486a857 100644 --- a/src/steam/fixture/model-port-registry.hpp +++ b/src/steam/fixture/model-port-registry.hpp @@ -17,7 +17,7 @@ ** While client code accesses model ports only as immutable descriptors handled ** through an (opaque) reference, the builder is in charge of detecting and organising ** any (new) model ports arising as the result of the build process. Changes to the set - ** of current model ports are to be activated with an atomic transactional switch. + ** of current model ports are to be activated with an atomic _transactional switch_. ** ** builder::ModelPortRegistry thus acts as management interface and factory for model ports. ** A given instance of this registry can be promoted to be "the" model port registry reflecting diff --git a/src/steam/fixture/segment.hpp b/src/steam/fixture/segment.hpp index a82fa30be..6fbddce97 100644 --- a/src/steam/fixture/segment.hpp +++ b/src/steam/fixture/segment.hpp @@ -48,7 +48,7 @@ namespace fixture { /** * For the purpose of building and rendering, the fixture (for each timeline) - * is partitioned such that each segment is _structurally constant._ + * is partitioned such that each segment is _structurally constant_. * For each segment there is a RenderGraph (unit of the render engine) * which is able to render all ExitNode(s) for this segment. * diff --git a/src/steam/fixture/segmentation.hpp b/src/steam/fixture/segmentation.hpp index 07dbefbfa..ff15ed96d 100644 --- a/src/steam/fixture/segmentation.hpp +++ b/src/steam/fixture/segmentation.hpp @@ -61,7 +61,7 @@ namespace fixture { /** * For the purpose of building and rendering, the fixture (for each timeline) - * is partitioned such that each segment is _structurally constant._ + * is partitioned such that each segment is _structurally constant_. * The Segmentation defines and maintains this partitioning. Furthermore, * it is the general entry point for accessing the correct part of the engine * responsible for a given timeline time point. diff --git a/src/steam/mobject/interpolator.hpp b/src/steam/mobject/interpolator.hpp index a526550cc..93c2db5a5 100644 --- a/src/steam/mobject/interpolator.hpp +++ b/src/steam/mobject/interpolator.hpp @@ -13,9 +13,9 @@ /** @file interpolator.hpp - ** Core abstraction: automation parameter interpolator + ** Core abstraction: automation parameter interpolator. ** Each interpolator implementation has the ability to resolve intermediary - ** values and to provide a parameter value for _every arbitrary point in time._ + ** values and to provide a parameter value for _every arbitrary point in time_. */ diff --git a/src/steam/mobject/model-port.hpp b/src/steam/mobject/model-port.hpp index 71024939a..b07b3fa67 100644 --- a/src/steam/mobject/model-port.hpp +++ b/src/steam/mobject/model-port.hpp @@ -31,7 +31,7 @@ ** has an associated StreamType. ** ** Because model ports are discovered this way, dynamically during the build process, - ** at some point there is a transactional switch to promote the new configuration + ** at some point there is a _transactional switch_ to promote the new configuration ** to become the valid current model port configuration. After that switch, model ports ** are immutable. ** diff --git a/src/steam/mobject/output-mapping.hpp b/src/steam/mobject/output-mapping.hpp index f7fdf03fc..bccea178b 100644 --- a/src/steam/mobject/output-mapping.hpp +++ b/src/steam/mobject/output-mapping.hpp @@ -107,7 +107,7 @@ namespace mobject { * This is an generic map-like container, acting as Interface to be used * in the signature of API functions either providing or requiring a Mapping. * For each distinct usage situation, an instantiation of this template should - * be created, providing a definition context as template parameter. + * be created, providing a _definition context_ as template parameter. * Instances of this concrete mapping type may then be default constructed * and copied freely. The definition context is supposed to provide * - a functor `DEF::output` usable as function pipe-ID --> Target diff --git a/src/steam/mobject/session/effect.cpp b/src/steam/mobject/session/effect.cpp index e1cf82ebe..1a2bed066 100644 --- a/src/steam/mobject/session/effect.cpp +++ b/src/steam/mobject/session/effect.cpp @@ -24,7 +24,7 @@ namespace mobject { namespace session { /** - * @TODO: clarify asset->mobject relation and asset dependencies; Ticket #255 + * @todo: clarify asset->mobject relation and asset dependencies; /////////////////////////////////////////TICKET #255 */ asset::Proc const& Effect::getProcAsset() const diff --git a/src/steam/mobject/session/scope.hpp b/src/steam/mobject/session/scope.hpp index d6cc19f12..1d80c9f51 100644 --- a/src/steam/mobject/session/scope.hpp +++ b/src/steam/mobject/session/scope.hpp @@ -46,18 +46,18 @@ namespace session { * Within the Session/Model, Placements are used to attach * MObjects; but beyond that, each Placement can \em contain * other Placements, effectively forming a scope. Thus Scope - * is basically another view on Placements which are attached - * to the session. This (hidden) link to the session is utilised + * is basically another view on Placements _which are attached + * to the session_. This (hidden) link to the session is utilised * to establish the nesting of scopes and allow querying and navigating. * * Actually, Scope is implemented through a PlacementRef pointing to - * the Placement which \em constitutes this Scope. We call this Placement - * the "scope top". A fork e.g. can \em contain several clips, but also + * the Placement which _constitutes this Scope_. We call this Placement + * the "scope top". A fork e.g. can _contain_ several clips, but also * nested sub forks, all of which would be within the scope of this fork. - * This scoping relation plays an important role when it comes to \em resolving + * This scoping relation plays an important role when it comes to _resolving_ * properties of placement, like e.g. the output designation, overlay mode, * sound pan position etc -- properties from enclosing scopes will be - * inherited unless \em shaded by local definitions, similar to the + * inherited unless _shaded_ by local definitions, similar to the * behaviour known from most programming languages when referring * to local variables. * @note Scope is a passive entity, diff --git a/src/steam/mobject/session/session-services.cpp b/src/steam/mobject/session/session-services.cpp index 803bd3aad..a95e8d985 100644 --- a/src/steam/mobject/session/session-services.cpp +++ b/src/steam/mobject/session/session-services.cpp @@ -103,7 +103,7 @@ namespace session { } - /** detach the denoted element from the model _including all children._ + /** detach the denoted element from the model _including all children_. * @return true if actually erased something * @note when specifying model root, all sub-elements will be cleared, * but model root itself will be retained. diff --git a/src/steam/mobject/session/session.cpp b/src/steam/mobject/session/session.cpp index c76bff798..6f8771a27 100644 --- a/src/steam/mobject/session/session.cpp +++ b/src/steam/mobject/session/session.cpp @@ -57,8 +57,8 @@ namespace mobject { * implementation object, where the smart pointer is actually * the SessionManager (which is singleton as well...). * - * Consequently, if you want to talk to the session manager, - * you use dot-notation, while you access the session object + * Consequently, if you want to talk to the _session manager_, + * you use dot-notation, while you access the _session object_ * via arrow notation (e.g. `Session::current->getFixture()` ) */ SessManager& Session::current = theSessionManager(); diff --git a/src/vault/gear/activity-term.hpp b/src/vault/gear/activity-term.hpp index 488e12f15..2d62d07e9 100644 --- a/src/vault/gear/activity-term.hpp +++ b/src/vault/gear/activity-term.hpp @@ -175,7 +175,7 @@ namespace gear { /** * Builder operation: append a Notification link to the end of this Term's chain. * @param targetTerm another Term, which thereby becomes dependent on this Term. - * @remark the \q targetTerm will be inhibited, until this Term's chain has + * @remark the \a targetTerm will be inhibited, until this Term's chain has * been activated and processed up to emitting the inserted `NOTIFY`. */ Term& diff --git a/src/vault/gear/block-flow.hpp b/src/vault/gear/block-flow.hpp index db06ac3a3..bb29f7afc 100644 --- a/src/vault/gear/block-flow.hpp +++ b/src/vault/gear/block-flow.hpp @@ -214,7 +214,7 @@ namespace gear { /** * Allocation Extent holding _scheduler Activities_ to be performed altogether - * before a common _deadline._ Other than the underlying raw Extent, the Epoch + * before a common _deadline_. Other than the underlying raw Extent, the Epoch * maintains a deadline time and keeps track of storage slots already claimed. * This is achieved by using the Activity record in the first slot as a GATE term * to maintain those administrative information. diff --git a/tests/basics/typed-counter-test.cpp b/tests/basics/typed-counter-test.cpp index d1d71f18b..4ae103354 100644 --- a/tests/basics/typed-counter-test.cpp +++ b/tests/basics/typed-counter-test.cpp @@ -138,7 +138,7 @@ namespace test{ /** * Helper for #tortureTest(): * Build a table of functors, where the i-th entry invokes the function - * increment(), which leads to incrementing the counter for Dummy. + * `increment()`, which leads to incrementing the counter for `Dummy`. */ template static auto @@ -163,7 +163,7 @@ namespace test{ * - run a large number of threads in parallel, each incrementing * a randomly picked counter; this is achieved by using a table * of »increment operators«, where each one is tied to a specific - * Dummy. + * `Dummy`. */ void tortureTest() diff --git a/tests/basics/visitingtool-concept.cpp b/tests/basics/visitingtool-concept.cpp index 0499066e6..9166a8c36 100644 --- a/tests/basics/visitingtool-concept.cpp +++ b/tests/basics/visitingtool-concept.cpp @@ -19,23 +19,22 @@ ** for the drafting process and is self-contained. The final solution was ** then extracted later as library implementation into visitor.hpp ** - ** Basic considerations - **
  • cyclic dependencies should be avoided or at least restricted - ** to some library related place. The responsibilities for - ** user code should be as small as possible.
    • - **
  • Visitor is about double dispatch, thus we can't avoid - ** using some table lookup implementation, and we can't avoid using - ** some of the cooperating classes' vtables. Besides that, the - ** implementation should not be too wasteful...
    • - **
  • individual Visiting Tool implementation classes should be able - ** to opt in or opt out on implementing functions treating some of - ** the visitable subclasses.
    • - **
  • there should be a safe fallback mechanism backed by the - ** visitable object's hierarchy relations. If some new class declares - ** to be visitable, existing Visiting Tools not yet treating this new - ** visitable type should fall back rather to the next best match up the - ** hierarchy, instead of invoking some almost abstract base class
    • - **
+ ** \par Basic considerations + ** - cyclic dependencies should be avoided or at least restricted + ** to some library related place. The responsibilities for + ** user code should be as small as possible. + ** - the purpose of Visitor is to achieve **double dispatch**, thus we + ** can not avoid using some table lookup implementation, and we can not + ** avoid using some of the cooperating classes' vtables. Besides that, + ** the implementation should not be too wasteful... + ** - individual Visiting Tool implementation classes should be able + ** to opt in or opt out on implementing functions treating some of + ** the visitable subclasses. + ** - there should be a safe fallback mechanism backed by the + ** visitable object's hierarchy relations. If some new class declares + ** to be visitable, existing Visiting Tools not yet treating this new + ** visitable type should fall back rather to the next best match up the + ** hierarchy, instead of invoking some almost abstract base class. ** ** @see visitor.hpp the final lib implementation ** @see visitingtooltest.cpp test cases using our lib implementation diff --git a/tests/core/application/subsystem-runner-test.cpp b/tests/core/application/subsystem-runner-test.cpp index ba7580e4a..c677de9a5 100644 --- a/tests/core/application/subsystem-runner-test.cpp +++ b/tests/core/application/subsystem-runner-test.cpp @@ -13,7 +13,7 @@ /** @file subsystem-runner-test.cpp ** The \ref SubsystemRunner_test performs various scenarios - ** regarding start, stop and failure of _Subsystems._ Its primary + ** regarding start, stop and failure of _Subsystems_. Its primary ** purpose is to cover the \ref SubsystemRunner. */ diff --git a/tests/core/steam/engine/buffer-proxy-provider-test.cpp b/tests/core/steam/engine/output-proxy-provider-test.cpp similarity index 98% rename from tests/core/steam/engine/buffer-proxy-provider-test.cpp rename to tests/core/steam/engine/output-proxy-provider-test.cpp index 8bcc8aabc..b977acb68 100644 --- a/tests/core/steam/engine/buffer-proxy-provider-test.cpp +++ b/tests/core/steam/engine/output-proxy-provider-test.cpp @@ -11,7 +11,7 @@ * *****************************************************************/ -/** @file output-proxy-provider-test.cpp +/** @file output-proxy-provider-test.cpp ** unit test \ref OutputProxyProvider_test */ diff --git a/tests/core/steam/mobject/builder/builder-tool-test.cpp b/tests/core/steam/mobject/builder/builder-tool-test.cpp index e078fe10f..5b1bd9c61 100644 --- a/tests/core/steam/mobject/builder/builder-tool-test.cpp +++ b/tests/core/steam/mobject/builder/builder-tool-test.cpp @@ -54,7 +54,7 @@ namespace test { * and DummyMO objects (wrapped into any acceptable shared-ptr). * Intentionally, we omit to declare it applicable to TestSubMO2 instances. * In reality this would be a case of misconfiguration, because TestSubMO2 - * is defined to be processable and consequently has an \apply() function, + * is defined to be processable and consequently has an `apply()` function, * which, due to this omission can't find a dispatcher entry when invoked, * so it will call the \c onUnknown(Buildable&) instead */ diff --git a/tests/library/hetero-data-test.cpp b/tests/library/hetero-data-test.cpp index 0197ad590..fb2c1a5a8 100644 --- a/tests/library/hetero-data-test.cpp +++ b/tests/library/hetero-data-test.cpp @@ -11,7 +11,7 @@ * *****************************************************************/ -/** @file del-stash-test.cpp +/** @file hetero-data-test.cpp ** unit test \ref HeteroData_test */ diff --git a/tests/library/index-iter-test.cpp b/tests/library/index-iter-test.cpp index 04f77e10f..7222ddac1 100644 --- a/tests/library/index-iter-test.cpp +++ b/tests/library/index-iter-test.cpp @@ -11,7 +11,7 @@ * *****************************************************************/ -/** @file iter-index-test.cpp +/** @file index-iter-test.cpp ** unit test \ref IndexIter_test */ diff --git a/tests/vault/gear/stress-test-rig.hpp b/tests/vault/gear/stress-test-rig.hpp index 658081966..5169e8a29 100644 --- a/tests/vault/gear/stress-test-rig.hpp +++ b/tests/vault/gear/stress-test-rig.hpp @@ -165,7 +165,7 @@ namespace test { /** * Configurable template framework for running Scheduler Stress tests * Use to build a custom setup class, which is then [injected](\ref StressTestRig::with) - * to [perform](\ref StressTestRig::Launcher::perform) a _specific measurement tool._ + * to [perform](\ref StressTestRig::Launcher::perform) a _specific measurement tool_. * Several tools and detailed customisations are available in `namespace bench` * - bench::BreakingPoint conducts a binary search to _break a schedule_ * - bench::ParameterRange performs a randomised series of parametrised test runs diff --git a/wiki/thinkPad.ichthyo.mm b/wiki/thinkPad.ichthyo.mm index 7f8f6df8c..099dba5f6 100644 --- a/wiki/thinkPad.ichthyo.mm +++ b/wiki/thinkPad.ichthyo.mm @@ -160496,8 +160496,8 @@ actively maintained upstream. Please remove gdl from Debian. - - + + @@ -160785,10 +160785,98 @@ Since then others have made contributions, see the log for the history. - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ das wirkt zwar offensichtlich im ersten Teil, wenn die source-Files erstmals geparst werden, denn dann werden (nur mit diesem Setting) alle Cores zu 100% ausgelastet +

+ + + + + + + + + + + + + + +

+ ...und zwar in der der _speziellen Form mit Unterstrich._  (meint: der Unterstrich steht hinter dem Punkt, und damit nicht mehr im \brief -Teil +

+ + + + + + + +

+ (wird als HTML-Trag geparst) +

+ + + + + + + + + + +

+ das Ergebnis ist letztlich immer wieder enttäuschend +

+ + + + + + +

+ Doxygen (wie auch diverse andere Sourcecode-Scanner und Validatoren) passen konzeptionell nicht sonderlich gut auf die spezielle Struktur von C++ Code, welcher sehr stark auf Scopes und Querbezüge setzt. Und mein eigener Code-Stil trägt dazu auch noch einiges bei. Meistens sind nur die Texte in den Header-Kommentaren brauchbar. Es folgt dann eine mehr-oder-weniger willkürlich wirkende Liste von Klassen und namespace-Membern. Eine solche Liste erzählt keine Geschichte (der Code tut es schon). Und der Umstand, daß in Doxygen die Struktur flach geklopft wird, tut ein Übriges +

+ + @@ -161265,7 +161353,7 @@ Since then others have made contributions, see the log for the history. - + @@ -161302,7 +161390,7 @@ Since then others have made contributions, see the log for the history. - + @@ -161611,11 +161699,13 @@ Since then others have made contributions, see the log for the history. - + + + - - - + + + @@ -161643,17 +161733,17 @@ Since then others have made contributions, see the log for the history. - + - - + + - + - + @@ -161688,8 +161778,8 @@ Since then others have made contributions, see the log for the history. - - + + @@ -161919,15 +162009,16 @@ Since then others have made contributions, see the log for the history. - + + - + - + @@ -161935,15 +162026,14 @@ Since then others have made contributions, see the log for the history. - - + - + @@ -161951,11 +162041,10 @@ Since then others have made contributions, see the log for the history. - - + - + @@ -161973,9 +162062,9 @@ Since then others have made contributions, see the log for the history. - - - + + + @@ -162000,10 +162089,9 @@ Since then others have made contributions, see the log for the history.SCHWEIN gehabt

- - + - + @@ -162017,13 +162105,33 @@ Since then others have made contributions, see the log for the history. - + + + + + + - + + + + + + + + + + + + + + + +