DOC: reorganise the Doxygen configuration and structure

- upgrade the configuration to a current version
- provide a frontpage with cross-links to other documentation
- define a set of modules; relevant classes and files can be
  added to these, to create a exploration path for new readers
- fix a lot of errors in documentation comments
- use a custom configuration for the documentation pages
- tweak the navigation, the sections and further arrangements

.gitignore

@@ -23,4 +23,5 @@ semantic.cache
 wiki/backups/*
 doc/devel/draw/*.png
 doc/devel/uml/fig128309.png
+doc/devel/lumiera.tag
 m4/*

admin/scons/BuilderDoxygen.py

@@ -59,30 +59,30 @@ def DoxyfileParse(file_contents):
             data[key][-1] += token
     
     while token:
-       if token in ['\n']:
+        if token in ['\n']:
-          if last_token not in ['\\']:
+            if last_token not in ['\\']:
-              key_token = True
+                key_token = True
-       elif token in ['\\']:
+        elif token in ['\\']:
-           pass
+            pass
-       elif key_token:
+        elif key_token:
-           key = token
+            key = token
-           key_token = False
+            key_token = False
-       else:
+        else:
-           if token == "+=":
+            if token == "+=":
-               if not data.has_key(key):
+                if not data.has_key(key):
-                   data[key] = list()
+                    data[key] = list()
-           elif token == "=":
+            elif token == "=":
-               data[key] = list()
+                data[key] = list()
-           else:
+            else:
-               append_data( data, key, new_data, token )
+                append_data(data, key, new_data, token)
-               new_data = True
+                new_data = True
-       
+        
-       last_token = token
+        last_token = token
-       token = lex.get_token()
+        token = lex.get_token()
-       
+        
-       if last_token == '\\' and token != '\n':
+        if last_token == '\\' and token != '\n':
-           new_data = False
+            new_data = False
-           append_data( data, key, new_data, '\\' )
+            append_data(data, key, new_data, '\\')
     
     # compress lists of len 1 into single strings
     for (k, v) in data.items():

doc/SConscript

@@ -3,7 +3,6 @@
 ## SConscript  -  SCons buildscript for Documentation
 ##
 
-from Buildhelper import scanSubtree
 
 Import('env')
 

doc/devel/Doxyfile

@@ -1,4 +1,4 @@
-# Doxyfile 1.5.6
+# Doxyfile 1.8.1.2
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -6,7 +6,9 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = Lumiera
 PROJECT_NUMBER         = 0.1+pre
-OUTPUT_DIRECTORY       = 
+PROJECT_BRIEF          =
+PROJECT_LOGO           = draw/rendered/LumiLogo-small.png
+OUTPUT_DIRECTORY       =
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
@@ -24,63 +26,62 @@ ABBREVIATE_BRIEF       = "The $name class" \
                          the
 ALWAYS_DETAILED_SEC    = YES
 INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
 STRIP_FROM_PATH        = ../../src/ \
                          ../../tests/
-STRIP_FROM_INC_PATH    = 
+STRIP_FROM_INC_PATH    = ../../src/
 SHORT_NAMES            = NO
 JAVADOC_AUTOBRIEF      = YES
 QT_AUTOBRIEF           = NO
 MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = YES
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = NO
 TAB_SIZE               = 4
-ALIASES                = 
+ALIASES                =
-OPTIMIZE_OUTPUT_FOR_C  = NO
+EXTENSION_MAPPING      =
-OPTIMIZE_OUTPUT_JAVA   = NO
+MARKDOWN_SUPPORT       = YES
-OPTIMIZE_FOR_FORTRAN   = NO
-OPTIMIZE_OUTPUT_VHDL   = NO
 BUILTIN_STL_SUPPORT    = YES
-CPP_CLI_SUPPORT        = NO
-SIP_SUPPORT            = NO
-IDL_PROPERTY_SUPPORT   = YES
 DISTRIBUTE_GROUP_DOC   = NO
 SUBGROUPING            = YES
-TYPEDEF_HIDES_STRUCT   = NO
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = YES
+TYPEDEF_HIDES_STRUCT   = YES
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
 EXTRACT_ALL            = NO
 EXTRACT_PRIVATE        = YES
+EXTRACT_PACKAGE        = NO
 EXTRACT_STATIC         = YES
 EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
-EXTRACT_ANON_NSPACES   = YES
 HIDE_UNDOC_MEMBERS     = NO
 HIDE_UNDOC_CLASSES     = NO
 HIDE_FRIEND_COMPOUNDS  = NO
 HIDE_IN_BODY_DOCS      = NO
 INTERNAL_DOCS          = YES
 CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 SHOW_INCLUDE_FILES     = YES
+FORCE_LOCAL_INCLUDES   = YES
 INLINE_INFO            = YES
 SORT_MEMBER_DOCS       = NO
 SORT_BRIEF_DOCS        = YES
+SORT_MEMBERS_CTORS_1ST = YES
 SORT_GROUP_NAMES       = NO
 SORT_BY_SCOPE_NAME     = NO
-GENERATE_TODOLIST      = NO
+STRICT_PROTO_MATCHING  = NO
-GENERATE_TESTLIST      = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
 GENERATE_BUGLIST       = NO
 GENERATE_DEPRECATEDLIST= NO
-ENABLED_SECTIONS       = 
+ENABLED_SECTIONS       =
-MAX_INITIALIZER_LINES  = 30
+MAX_INITIALIZER_LINES  = 0
 SHOW_USED_FILES        = YES
-SHOW_DIRECTORIES       = NO
 SHOW_FILES             = YES
 SHOW_NAMESPACES        = YES
-FILE_VERSION_FILTER    = 
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
@@ -88,67 +89,38 @@ QUIET                  = NO
 WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = NO
 WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = YES
+WARN_NO_PARAMDOC       = NO
 WARN_FORMAT            = "$file:$line: $text"
-WARN_LOGFILE           = warnings.txt
+WARN_LOGFILE           = html/doxygen-warnings.txt
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../../src/
 INPUT_ENCODING         = UTF-8
+INPUT                  = ../../src/ \
+                         ../../tests \
+                         ../../admin/scons
 FILE_PATTERNS          = *.c \
                          *.cc \
-                         *.cxx \
                          *.cpp \
-                         *.c++ \
-                         *.d \
-                         *.java \
-                         *.ii \
-                         *.ixx \
-                         *.ipp \
-                         *.i++ \
-                         *.inl \
                          *.h \
                          *.hh \
-                         *.hxx \
                          *.hpp \
-                         *.h++ \
-                         *.idl \
-                         *.odl \
-                         *.cs \
-                         *.php \
-                         *.php3 \
                          *.inc \
-                         *.m \
-                         *.mm \
                          *.dox \
-                         *.py \
+                         *.py
-                         *.C \
-                         *.CC \
-                         *.C++ \
-                         *.II \
-                         *.I++ \
-                         *.H \
-                         *.HH \
-                         *.H++ \
-                         *.CS \
-                         *.PHP \
-                         *.PHP3 \
-                         *.M \
-                         *.MM \
-                         *.PY
 RECURSIVE              = YES
-EXCLUDE                = 
+EXCLUDE                =
 EXCLUDE_SYMLINKS       = YES
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       =
-EXCLUDE_SYMBOLS        = 
+EXCLUDE_SYMBOLS        =
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           =
-EXAMPLE_PATTERNS       = *
+EXAMPLE_PATTERNS       =
 EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
+IMAGE_PATH             =
-INPUT_FILTER           = 
+INPUT_FILTER           =
-FILTER_PATTERNS        = 
+FILTER_PATTERNS        =
 FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
 #---------------------------------------------------------------------------
@@ -157,14 +129,14 @@ INLINE_SOURCES         = NO
 STRIP_CODE_COMMENTS    = YES
 REFERENCED_BY_RELATION = YES
 REFERENCES_RELATION    = YES
-REFERENCES_LINK_SOURCE = YES
+REFERENCES_LINK_SOURCE = NO
 USE_HTAGS              = NO
 VERBATIM_HEADERS       = YES
 #---------------------------------------------------------------------------
 # configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
 ALPHABETICAL_INDEX     = YES
-COLS_IN_ALPHA_INDEX    = 5
+COLS_IN_ALPHA_INDEX    = 1
 IGNORE_PREFIX          = lumiera:: \
                          lumiera_ \
                          lumi_ \
@@ -175,26 +147,27 @@ IGNORE_PREFIX          = lumiera:: \
 GENERATE_HTML          = YES
 HTML_OUTPUT            = html
 HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = 
+HTML_HEADER            =
-HTML_FOOTER            = 
+HTML_FOOTER            =
-HTML_STYLESHEET        = 
+HTML_STYLESHEET        =
-HTML_ALIGN_MEMBERS     = YES
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 344
+HTML_COLORSTYLE_SAT    = 68
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = YES
+HTML_DYNAMIC_SECTIONS  = YES
+HTML_INDEX_NUM_ENTRIES = 100
 GENERATE_HTMLHELP      = NO
-GENERATE_DOCSET        = NO
+GENERATE_ECLIPSEHELP   = NO
-DOCSET_FEEDNAME        = "Lumiera Doxygen docs"
+TOC_EXPAND             = YES
-DOCSET_BUNDLE_ID       = org.doxygen.Project
-HTML_DYNAMIC_SECTIONS  = NO
-CHM_FILE               = 
-HHC_LOCATION           = 
-GENERATE_CHI           = NO
-CHM_INDEX_ENCODING     = 
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
 DISABLE_INDEX          = NO
-ENUM_VALUES_PER_LINE   = 4
 GENERATE_TREEVIEW      = YES
-TREEVIEW_WIDTH         = 250
+TREEVIEW_WIDTH         = 200
-FORMULA_FONTSIZE       = 10
+ENUM_VALUES_PER_LINE   = 1
+FORMULA_FONTSIZE       = 9
+FORMULA_TRANSPARENT    = YES
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
 #---------------------------------------------------------------------------
 # configuration options related to the LaTeX output
 #---------------------------------------------------------------------------
@@ -204,80 +177,58 @@ LATEX_CMD_NAME         = latex
 MAKEINDEX_CMD_NAME     = makeindex
 COMPACT_LATEX          = YES
 PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         = 
+EXTRA_PACKAGES         =
-LATEX_HEADER           = 
+LATEX_HEADER           =
+LATEX_FOOTER           =
 PDF_HYPERLINKS         = YES
 USE_PDFLATEX           = YES
 LATEX_BATCHMODE        = YES
 LATEX_HIDE_INDICES     = NO
+LATEX_SOURCE_CODE      = NO
+LATEX_BIB_STYLE        = plain
 #---------------------------------------------------------------------------
-# configuration options related to the RTF output
+# configuration options related to other output formats
 #---------------------------------------------------------------------------
 GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    = 
-RTF_EXTENSIONS_FILE    = 
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
 GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
 GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             = 
-XML_DTD                = 
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
 GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
 GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX = 
 #---------------------------------------------------------------------------
-# Configuration options related to the preprocessor   
+# Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = NO
 EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
+INCLUDE_PATH           =
-INCLUDE_FILE_PATTERNS  = 
+INCLUDE_FILE_PATTERNS  =
-PREDEFINED             = 
+PREDEFINED             =
-EXPAND_AS_DEFINED      = 
+EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
-# Configuration::additions related to external references   
+# Configuration::additions related to external references
 #---------------------------------------------------------------------------
-TAGFILES               = 
+TAGFILES               =
-GENERATE_TAGFILE       = 
+GENERATE_TAGFILE       = lumiera.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 PERL_PATH              = /usr/bin/perl
 #---------------------------------------------------------------------------
-# Configuration options related to the dot tool   
+# Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            = 
+MSCGEN_PATH            =
 HIDE_UNDOC_RELATIONS   = YES
 HAVE_DOT               = YES
 DOT_FONTNAME           = FreeSans
-DOT_FONTPATH           = 
+DOT_FONTSIZE           = 8
+DOT_FONTPATH           =
 CLASS_GRAPH            = YES
 COLLABORATION_GRAPH    = YES
 GROUP_GRAPHS           = YES
 UML_LOOK               = YES
+UML_LIMIT_NUM_FIELDS   = 8
 TEMPLATE_RELATIONS     = YES
 INCLUDE_GRAPH          = NO
 INCLUDED_BY_GRAPH      = NO
@@ -285,16 +236,11 @@ CALL_GRAPH             = YES
 CALLER_GRAPH           = YES
 GRAPHICAL_HIERARCHY    = NO
 DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = svg
-DOT_PATH               = 
+INTERACTIVE_SVG        = YES
-DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 80
-DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 1000
-DOT_TRANSPARENT        = NO
+DOT_TRANSPARENT        = YES
 DOT_MULTI_TARGETS      = YES
 GENERATE_LEGEND        = YES
 DOT_CLEANUP            = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine   
-#---------------------------------------------------------------------------
-SEARCHENGINE           = NO

doc/devel/DoxygenLayout.xml

@@ -0,0 +1,190 @@
+<doxygenlayout version="1.0">
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title="Lumiera API Documentation"/>
+    <tab type="user" url="http://Lumiera.org/documentation/user/intro/intro.html" title="Intro"/>
+    <tab type="user" url="http://Lumiera.org/documentation/technical/overview.html" title="Overview"/>
+    <tab type="modules" visible="yes" title="" intro="Subsystems"/>
+    <tab type="classes" visible="yes" title="">
+      <tab type="classlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="hierarchy" visible="no" title="" intro=""/>
+      <tab type="classmembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="yes" title="">
+      <tab type="filelist" visible="yes" title="" intro=""/>
+      <tab type="globals" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="pages" visible="yes" title="" intro=""/>
+    <tab type="examples" visible="yes" title="" intro=""/>  
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="no"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <allmemberslink visible="yes"/>
+    <detaileddescription title="Description"/>
+    <memberdecl>
+      <publictypes title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicstaticattributes title=""/>
+      <publicattributes title=""/>
+      <nestedclasses visible="yes" title=""/>
+      <friends title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <memberdef>
+      <typedefs title=""/>
+      <enums title=""/>
+      <inlineclasses title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <properties title=""/>
+      <variables title=""/>
+      <events title=""/>
+      <related title=""/>
+    </memberdef>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="no"/>
+    <detaileddescription title="Description"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <classes visible="yes" title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <memberdef>
+      <typedefs title=""/>
+      <enums title=""/>
+      <inlineclasses title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="no"/>
+    <sourcelink visible="yes"/>
+    <detaileddescription title="Description"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <memberdecl>
+      <classes visible="yes" title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <defines title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <namespaces visible="yes" title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <memberdef>
+      <typedefs title=""/>
+      <enums title=""/>
+      <defines title=""/>
+      <inlineclasses title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="no"/>
+    <detaileddescription title="Description"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <groupgraph visible="$GROUP_GRAPHS"/>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>
+

doc/index.txt

@@ -1,5 +1,7 @@
+Documentation
+=============
 
-= Documentation =
+// Menu :  append child 'doxy'
 
 This documentation section contains documentation for both users and developers.
 
@@ -32,6 +34,11 @@ moved over to the documentation section(s) of the Lumiera website.
 
 -> access the Proc-Layer link:http://lumiera.org/wiki/renderengine.html[TiddlyWiki online here]
 
+=== API Documentation ===
+We use the link:http://www.doxygen.org/index.html[Doxygen] tool to extract
+code comments and generate code level API and reference documentation.
+
+-> link:http://lumiera.org/doxy/index.html[Doxygen generated documentation]
 
 == Media and Presentations ==
 

src/backend/engine/scheduler-frontend.hpp

@@ -44,6 +44,8 @@ namespace engine {
    * handed over to the scheduler for time-bound or bandwidth-controlled
    * execution
    * 
+   * @ingroup engine
+   * @ingroup scheduler
    * @todo this is planned to become the frontend
    * to the render node network, which can be considered
    * at the lower end of the middle layer; the actual 

src/backend/resourcecollector.h

@@ -126,13 +126,14 @@ lumiera_resourcecollector_destroy (void);
  *                (to find out about the device) for STORAGE and CACHE resources
  * @return either returns 1 or calls _exit()
  *
- * @example
+ * @code
  * void* data;
  * size_t size = 1000;
  * enum lumiera_resource_try iteration = LUMIERA_RESOURCE_ONE;
  * do {
  *   data = malloc (size);
  * } while (!data && lumiera_resourcecollector_run (LUMIERA_RESOURCE_MEMORY, &iteration, &size));
+ * @endcode
  */
 int
 lumiera_resourcecollector_run (enum lumiera_resource which, enum lumiera_resource_try* iteration, void* context);

src/doxygen.dox

@@ -0,0 +1,101 @@
+/*
+  DOXYGEN.dox  -  font page for the Doxygen API documentation
+ 
+
+  Copyright (C)         Lumiera.org
+    2013,               Hermann Vosseler <Ichthyostega@web.de>
+                        Christian Thaeter <ct@pipapo.org>
+
+  This program is free software; you can redistribute it and/or
+  modify it under the terms of the GNU General Public License as
+  published by the Free Software Foundation; either version 2 of
+  the License, or (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program; if not, write to the Free Software
+  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+*/
+
+
+/** @mainpage Lumiera API Documentation
+
+This section contains the API and reference documentation
+of the Lumiera code base. It is generated automatically from the
+source code comments.
+
+Lumiera Documentation Structure
+===============================
+Lumiera comes with extensive documentation, which is organised into several tiers or layers,
+according to the target audience, the degree of detail and the level of technicality.
+Mostly, the sources of the documentation are kept in-tree; documentation pages are generated
+with the *ASCIIDOC* tool and published at the [Lumiera website](http://Lumiera.org/documentation)
+
+- as a general introduction, you should read the [»outer space« document](http://Lumiera.org/documentation/user/intro/intro.html)
+- further user documentation -- mostly tutorials -- is available in the [user section](http://Lumiera.org/documentation/user/)
+- Architecture and specification documents can be found in the [design section](http://www.lumiera.org/documentation/design/)
+- fundamental discussions and decisions are documented in the form of [RfC entries](http://www.lumiera.org/documentation/devel/design_process.html)
+- as entrance to the *technical level*, developers should read the [»inner core«](http://www.lumiera.org/documentation/technical/overview.html) document
+- from there, various pages in the [technical documentation](http://www.lumiera.org/documentation/technical) detail specific aspects
+  of implementation and technology. They treat some topics in a coherent fashion and introduce the concepts and abstractions
+  necessary to understand the actual code
+- right now, you are looking at the **API Documentation**, which is the entrance point to the actual code
+- on your exploration path down to the internal details, you might want to follow the overview given
+  + by the [Layer and Subsystem](modules.html) overview
+  + the file level comments of relevant interfaces
+
+*/
+
+/* ==== Layers ==== */
+
+/** @defgroup backend Backend-Layer
+*/
+
+/** @defgroup proc Proc-Layer
+*/
+
+/** @defgroup gui Graphical User Interface
+*/
+
+/* ==== Subsystems ==== */
+
+/** @defgroup asset Asset Management
+    @ingroup proc
+*/
+
+/** @defgroup session Session
+    @ingroup proc
+*/
+
+/** @defgroup player Playback and Render Control
+    @ingroup proc
+*/
+
+/** @defgroup engine Render Engine
+    @ingroup proc
+*/
+
+/** @defgroup scheduler Scheduler
+    @ingroup backend
+*/
+
+
+/* ==== Global Namespaces ==== */
+
+/** @namespace lumiera
+Lumiera public interface.
+Global interfaces and facilities accessible from plugins and scripts.
+It's probably a good idea to pull it in explicitly and to avoid nesting
+implementation namespaces within \c lumiera::
+*/
+
+
+/** @namespace lib
+Implementation namespace for support and library code.
+*/
+

src/gui/widgets/timeline/timeline-layout-helper.hpp

@@ -59,7 +59,7 @@ public:
   /**
    * Definition of the layout track tree type.
    */
-  typedef lumiera::tree< std::tr1::shared_ptr<model::Track> > TrackTree;
+  typedef lib::Tree< std::tr1::shared_ptr<model::Track> > TrackTree;
   
 public:
   /**

src/include/play-facade.h

@@ -64,6 +64,7 @@ namespace lumiera {
      * Global access point for starting playback and render processes,
      * calculating media data by running the render engine.
      * 
+     * @ingroup player
      * @todo WIP-WIP-WIP 6/2011
      * @note Lumiera is not yet able actually to deliver rendered data.
      * @todo there should be an accompanying CL Interface defined for
@@ -90,6 +91,7 @@ namespace lumiera {
          * through this handle (by ref count). Client code is supposed to use the
          * API on this handle to navigate and control the playback mode.
          * 
+         * @ingroup player
          * @see handle.hpp 
          * @see player-service.cpp implementation
          */

src/lib/depend.hpp

@@ -67,8 +67,8 @@ This code is heavily inspired by
  ** work besides releasing references, and we acknowledge that singletons can be released
  ** in \em arbitrary order.
  ** 
- ** @see Depend
+ ** @see lib::Depend
- ** @see DependencyFactory
+ ** @see lib::DependencyFactory
  ** @see lib::test::Depend4Test
  ** @see singleton-test.cpp
  ** @see dependency-factory-test.cpp
@@ -99,8 +99,6 @@ namespace lib {
    *   To my understanding, the answer is yes. See
    *   [POSIX](http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap04.html#tag_04_10)
    * @param SI the class of the Singleton instance
-   * @param Create policy defining how to create/destroy the instance
-   * @param Life policy defining how to manage Singleton Lifecycle
    */
   template<class SI>
   class Depend

src/lib/iter-adapter.hpp

@@ -617,9 +617,9 @@ namespace lib {
       
       /** explicit builder to allow creating a const variant from the basic srcIter type. 
        *  Again, the reason necessitating this "backdoor" is that we want to swallow one level
-       *  of indirection. Generally speaking \code const T ** \endcode is not the same as
+       *  of indirection. Generally speaking `const T **` is not the same as `T * const *`,
-       *  \code T * const * \endcode, but in our specific case the API ensures that a
+       *  but in our specific case the API ensures that a `PtrDerefIter<WrappedConstIterType>`
-       *  PtrDerefIter<WrappedConstIterType> only exposes const elements. 
+       *  only exposes const elements. 
        */
       static PtrDerefIter
       build_by_cast (WrappedIterType const& srcIter)

src/lib/lockerror.c

@@ -17,7 +17,9 @@
   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-*/
+
+* *****************************************************/
+
 
 #include "lib/lockerror.h"
 
@@ -29,7 +31,7 @@ LUMIERA_ERROR_DEFINE (LOCK_RELEASE, "unlocking failed");
 LUMIERA_ERROR_DEFINE (LOCK_DESTROY, "lock destroy failed");
 
 /* runtime errors */
-LUMIERA_ERROR_DEFINE (LOCK_INVAL, "lock initialization error");
+LUMIERA_ERROR_DEFINE (LOCK_INVAL, "lock initialisation error");
 LUMIERA_ERROR_DEFINE (LOCK_BUSY, "already locked");
 LUMIERA_ERROR_DEFINE (LOCK_DEADLK, "already locked by this thread");
 LUMIERA_ERROR_DEFINE (LOCK_PERM, "not locked by this thread");

src/lib/opaque-holder.hpp

@@ -196,8 +196,8 @@ namespace lib {
    * or cleared afterwards, and this #empty() state may be detected
    * at runtime. In a similar vein, when the stored object has a
    * \c bool validity check, this can be accessed though #isValid().
-   * Moreover \code !empty() && isValid() \endcode may be tested
+   * Moreover `!empty() && isValid()` may be tested as by `bool`
-   * as by \bool conversion of the Holder object. The whole compound
+   * conversion of the Holder object. The whole compound
    * is copyable if and only if the contained object is copyable.
    * 
    * @note assertion failure when trying to place an instance not

src/lib/ppmpl.h

@@ -37,18 +37,18 @@
  *
  * This user defined macro shall be undefed after use.
  *
- * @example
+ * @code
  * #define PPMPL_FOREACH_P1_FOO(arg) arg,
  *
  * {PPMPL_FOREACH(P1, FOO(1), FOO(2), FOO(3)), -1}
  *
  * #undef PPMPL_FOREACH_P1_FOO
+ * @endcode
  *
- * Would expand to the sequence:
+ * This definition would be expanded to the sequence `{1, 2, 3, -1}`
- * {1, 2, 3, -1}
  *
  * One can not recursively nest preprocessor macros. To allow this we define PPMPL_FOREACH_L1
- * to PPMPL_FOREACH_L2 with the same semantics as PPMPL_FOREACH, This allowes to nest the
+ * to PPMPL_FOREACH_L2 with the same semantics as PPMPL_FOREACH, This allows to nest the
  * FOREACH loop up to three nesting levels.
  */
 #define PPMPL_FOREACH(p, ...) PPMPL_FOREACH0(p, __VA_ARGS__, PPMPL_FOREACH_NIL))

src/lib/query-util.cpp

@@ -89,8 +89,7 @@ namespace lib {
     /** (preliminary) helper: instead of really parsing and evaluating the terms,
      *  just do a regular expression match to extract the literal argument 
      *  behind the given predicate symbol. e.g calling
-     *  \code extractID ("stream", "id(abc), stream(mpeg)") \endcode 
+     *  `extractID ("stream", "id(abc), stream(mpeg)")` yields \c "mpeg"
-     *  yields \c "mpeg"
      */
     string
     extractID (Symbol sym, const string& termString)

src/lib/sync.hpp

@@ -59,8 +59,8 @@
  ** @see mutex.h
  ** @see sync-locking-test.cpp
  ** @see sync-waiting-test.cpp
- ** @see asset::AssetManager::reg() usage example
+ ** @see \ref asset::AssetManager::reg() "usage example: asset registration"
- ** @see subsystemrunner.hpp usage example
+ ** @see \ref subsystem-runner.hpp "usage example: subsystem start/shutdown"
  */
 
 
@@ -74,6 +74,7 @@ extern "C" {
 #include "lib/lockerror.h"
 }
 
+#include <boost/noncopyable.hpp>
 #include <pthread.h>
 #include <cerrno>
 #include <ctime>
@@ -421,7 +422,11 @@ namespace lib {
       
       
     public:
+      /*****************************************//**
+       * scoped object to control the actual locking.
+       */
       class Lock
+        : boost::noncopyable
         {
           Monitor& mon_;
           

src/lib/variant.hpp

@@ -29,7 +29,7 @@
  ** Values can be stored using \c operator= . In order to access the value
  ** stored in lib::Variant, you additionally need to define a "functor" 
  ** - with a typedef "Ret" for the return type
- ** - providing a \code static Ret access(ELM&) \endcode function
+ ** - providing a `static Ret access(ELM&)` function
  **   for each of the types used in the Variant</li>
  ** 
  ** @todo the instance handling for the accessor seems somewhat

src/lib/visitor.hpp

@@ -59,7 +59,7 @@ Credits for many further implementation ideas go to
  **         on some treat(VisitableInterface&) function.</li>
  **     <li>any concrete Visitable subclass wanting to be treated by some concrete tool
  **         needs to use the DECLARE_PROCESSABLE_BY(TOOLBASE) macro. By this, it gets an
- **         virtual \code apply(TOOLBASE&) function. Otherwise, it will be treated by the
+ **         virtual `apply(TOOLBASE&)` function. Otherwise, it will be treated by the
  **         interface of the next base class using this macro.</li>
  ** </ul>
  ** For design questions and more detailed implementation notes, see the Proc Layer Tiddly Wiki.  

src/proc/asset.hpp

@@ -21,6 +21,7 @@
 */
 
 /** @file asset.hpp
+ ** @ingroup asset
  ** Proc-Layer Interface: Assets.
  ** Declares the Asset top level Interface, the Asset::Ident identification tuple
  ** and the asset::ID primary key wrapper. Normally, Assets should be handled
@@ -45,7 +46,7 @@
  ** (Implementation detail: as g++ is not able to handle member function template
  ** instantiations completely automatic, we need to trigger some template instantiations
  ** at the end of assetmanager.cpp )
- **
+ ** 
  ** @see assetmanager.hpp
  ** @see media.hpp
  */

src/proc/asset/media.hpp

@@ -23,10 +23,11 @@
 
 /** @file media.hpp
  ** Media data is a specific kind of Asset.
- ** For the different <i>kinds</i> of Assets, we use sub-intefaces inheriting
+ ** For the different <i>kinds</i> 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 specialization of the Asset ID.
+ ** directly from the AssetManager, we define a specialisation of the Asset ID.
- **
+ ** 
+ ** @ingroup asset
  ** @see asset.hpp for explanation
  ** @see MediaFactory creating concrete asset::Media instances
  **
@@ -119,7 +120,7 @@ namespace asset {
       
       /** predicate to decide if this asset::Media
        *  is part of a compound (multichannel) media.
-       *  @return pointer to parent, or \code null
+       *  @return pointer to parent, or `null`
        */
       virtual PMedia checkCompound ()  const;
       friend class proc::asset::Clip;    ////////////////////////TODO better interface!!!

src/proc/asset/meta.hpp

@@ -50,6 +50,7 @@
  ** or changed metadata entry, finally \em committing this builder to yield a new
  ** asset::Meta (which, in case of a mutation, might supersede an existing one).
  ** 
+ ** @ingroup asset
  ** @see asset.hpp explanation of assets in general
  ** @see MetaFactory creating concrete asset::Meta instances
  **

src/proc/asset/proc.hpp

@@ -27,6 +27,7 @@
  ** 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.
  ** 
+ ** @ingroup asset
  ** @see asset.hpp for explanation
  ** @see ProcFactory creating concrete asset::Proc instances
  **
@@ -66,6 +67,8 @@ namespace asset {
   /**
    * key abstraction: data processing asset
    * @todo just a stub, have to figure out what a asset::Proc is
+   * @ingroup asset
+   * @ingroup session
    */
   class Proc : public Asset
     {

src/proc/asset/struct.hpp

@@ -48,6 +48,7 @@
  ** all placements referring to this track, which could be sub tracks, clips,
  ** effects, automation or labels. 
  ** 
+ ** @ingroup asset
  ** @see asset.hpp for explanation regarding asset IDs
  ** @see StructFactory creating concrete asset::Struct instances
  **

src/proc/common.hpp

@@ -50,27 +50,6 @@
 #include "lib/error.hpp"   // pulls in NoBug via loggging.h
 
 
-/**
- * Lumiera public interface.
- * Global interfaces and facilities accessible from plugins and scripts.
- * It's probably a good idea to pull it in explicitly and to avoid nesting
- * implementation namespaces within \c lumiera::
- */
-namespace lumiera {
-
-  /* additional global configuration goes here... */
-  
-  
-} // namespace lumiera
-
-
-/**
- * Implementation namespace for support and library code.
- */
-namespace lib { 
-  
-}
-
 
 /**
  * Proc-Layer implementation namespace root.

src/proc/engine/engine-service.hpp

@@ -38,6 +38,7 @@
  ** switch and continuation; under the hood, there is a mechanism to discard resources
  ** tied to the original CalcStream, once the switch to the new definition is complete.
  ** 
+ ** @ingroup engine
  ** @see EngineInterface_test
  ** @see CalcStream_test
  ** @see proc::play::PlayerService
@@ -94,6 +95,8 @@ namespace engine{
    * backend layer. The implementation of this service is
    * responsible for creating the right job entries in the
    * correct order and to enqueue these into the scheduler.
+   * @ingroup engine
+   * @ingroup player
    */
   class EngineService
     : boost::noncopyable

src/proc/mobject/mobject.hpp

@@ -61,6 +61,7 @@ namespace mobject {
    * All the contents and elements that can be placed and 
    * manipulated and finally rendered within Lumiera's
    * high-level model and Session are MObjects.
+   * @ingroup session
    */
   class MObject 
     : public Buildable,

src/proc/mobject/session.hpp

@@ -22,6 +22,7 @@
 
 
 /** @file session.hpp
+ ** @ingroup session
  ** Primary Interface to the current Session.
  ** The session interface can be used to discover session's contents.
  ** Mostly, these objects within the session are MObject subclasses, but they
@@ -101,7 +102,8 @@ namespace mobject {
    *       a reference to the SessManager and is accessible as the static
    *       field Session::current). Clients shouldn't try to get a direct
    *       pointer or reference to the Session object.
-   *  
+   * @ingroup session
+   * 
    */
   class Session 
     : boost::noncopyable

src/proc/mobject/session/element-query.hpp

@@ -102,7 +102,7 @@ namespace session {
        *  @return MObject ref to the fist suitable element. Might be an empty MObjectRef.
        *  @note  the embedded MObject subtype (MO) causes an additional filtering
        *         on that specific kind of MObject (e.g. considering just Clips)
-       *  @warning be sure the passed predicate actually takes a \code Placement<XX> const& \endcode
+       *  @warning be sure the passed predicate actually takes a `Placement<XX> const&`
        *         with XX being the correct type. Note the \c const& -- Failing to do so shows up as
        *         compiler error "no suitable function pick(.....)"
        */

src/proc/mobject/session/session.cpp

@@ -64,7 +64,7 @@ namespace mobject {
    * 
    *  Consequently, if you want to talk to the <i>session manager,</i>
    *  you use dot-notation, while you access the <i>session object</i>
-   *  via arrow notation (e.g. \code Session::current->getFixture() )
+   *  via arrow notation (e.g. `Session::current->getFixture()` )
    */
   SessManager& Session::current = lib::Depend<SessManagerImpl>()();
   

src/proc/play/timings.hpp

@@ -140,7 +140,7 @@ namespace play {
       
       /** real time deadline for the given frame, without any latency.
        *  This value is provided in case of scheduled time of delivery,
-       *  which is signalled  by \code playbackUrgency == TIMEBOUND \endcode
+       *  which is signalled  by `playbackUrgency == TIMEBOUND`
        * @return wall clock time to expect delivery of data
        *         corresponding to a frame specified relative
        *         to \link #getOrigin time axis origin \endlink

tests/library/opaque-holder-test.cpp

@@ -111,7 +111,7 @@ namespace test{
    *        or a custom allocator.
    *
    *  @todo this test doesn't cover automatic conversions and conversions using RTTI
-   *        from the target objects, while \code OpaqueHolder.template get() \endcode
+   *        from the target objects, while `OpaqueHolder.template get()`
    *        would allow for such conversions. This is similar to Ticket #141, and
    *        actually based on the same code as variant.hpp (access-casted.hpp)
    */