ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

DOC: reorganise the Doxygen configuration and structure

Browse source 
- 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
This commit is contained in:
Fischlurch 2013-10-25 06:34:38 +02:00
parent 974c670d41
commit 6822a9e2fb
38 changed files with 772 additions and 547 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

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

48
admin/scons/BuilderDoxygen.py
View file

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

0
admin/scons/IconSvgRenderer.py Executable file → Normal file
View file

1
doc/SConscript
View file

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

218
doc/devel/Doxyfile
View file

@ -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 =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
ALIASES =
EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
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 = YES
EXTRACT_ANON_NSPACES = NO
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
GENERATE_TESTLIST = NO
STRICT_PROTO_MATCHING = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = NO
GENERATE_DEPRECATEDLIST= NO
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
ENABLED_SECTIONS =
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 \
*.C \
*.CC \
*.C++ \
*.II \
*.I++ \
*.H \
*.HH \
*.H++ \
*.CS \
*.PHP \
*.PHP3 \
*.M \
*.MM \
*.PY
*.py
RECURSIVE = YES
EXCLUDE =
EXCLUDE =
EXCLUDE_SYMLINKS = YES
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
IMAGE_PATH =
INPUT_FILTER =
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_FOOTER =
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
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
DOCSET_FEEDNAME = "Lumiera Doxygen docs"
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
GENERATE_ECLIPSEHELP = NO
TOC_EXPAND = YES
DISABLE_INDEX = NO
ENUM_VALUES_PER_LINE = 4
GENERATE_TREEVIEW = YES
TREEVIEW_WIDTH = 250
FORMULA_FONTSIZE = 10
TREEVIEW_WIDTH = 200
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 =
LATEX_HEADER =
EXTRA_PACKAGES =
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_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
TAGFILES =
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_PATH =
DOTFILE_DIRS =
DOT_GRAPH_MAX_NODES = 50
DOT_IMAGE_FORMAT = svg
INTERACTIVE_SVG = YES
DOT_GRAPH_MAX_NODES = 80
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

190
doc/devel/DoxygenLayout.xml Normal file
View file

@ -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>

145
doc/devel/draw/LumiLogo.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.8 KiB

After

Width:  |  Height:  |  Size: 9.1 KiB

9
doc/index.txt
View file

@ -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 ==

2
src/backend/engine/scheduler-frontend.hpp
View file

@ -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

3
src/backend/resourcecollector.h
View file

@ -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);

101
src/doxygen.dox Normal file
View file

@ -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.
*/

2
src/gui/widgets/timeline/timeline-layout-helper.hpp
View file

@ -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:
/**

2
src/include/play-facade.h
View file

@ -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
*/

6
src/lib/depend.hpp
View file

@ -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 DependencyFactory
** @see lib::Depend
** @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

6
src/lib/iter-adapter.hpp
View file

@ -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
* \code T * const * \endcode, but in our specific case the API ensures that a
* PtrDerefIter<WrappedConstIterType> only exposes const elements.
* of indirection. Generally speaking `const T **` is not the same as `T * const *`,
* but in our specific case the API ensures that a `PtrDerefIter<WrappedConstIterType>`
* only exposes const elements.
*/
static PtrDerefIter
build_by_cast (WrappedIterType const& srcIter)

6
src/lib/lockerror.c
View file

@ -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");

4
src/lib/opaque-holder.hpp
View file

@ -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
* as by \bool conversion of the Holder object. The whole compound
* Moreover `!empty() && isValid()` may be tested as by `bool`
* 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

8
src/lib/ppmpl.h
View file

@ -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:
* {1, 2, 3, -1}
* This definition would be expanded to the sequence `{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))

3
src/lib/query-util.cpp
View file

@ -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
* yields \c "mpeg"
* `extractID ("stream", "id(abc), stream(mpeg)")` yields \c "mpeg"
*/
string
extractID (Symbol sym, const string& termString)

9
src/lib/sync.hpp
View file

@ -59,8 +59,8 @@
** @see mutex.h
** @see sync-locking-test.cpp
** @see sync-waiting-test.cpp
** @see asset::AssetManager::reg() usage example
** @see subsystemrunner.hpp usage example
** @see \ref asset::AssetManager::reg() "usage example: asset registration"
** @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_;

497
src/lib/tree.hpp
View file

File diff suppressed because it is too large Load diff

2
src/lib/variant.hpp
View file

@ -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

2
src/lib/visitor.hpp
View file

@ -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.

3
src/proc/asset.hpp
View file

@ -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
*/

9
src/proc/asset/media.hpp
View file

@ -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!!!

1
src/proc/asset/meta.hpp
View file

@ -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
**

3
src/proc/asset/proc.hpp
View file

@ -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
{

1
src/proc/asset/struct.hpp
View file

@ -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
**

21
src/proc/common.hpp
View file

@ -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.

3
src/proc/engine/engine-service.hpp
View file

@ -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

1
src/proc/mobject/mobject.hpp
View file

@ -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,

4
src/proc/mobject/session.hpp
View file

@ -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

2
src/proc/mobject/session/element-query.hpp
View file

@ -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(.....)"
*/

2
src/proc/mobject/session/session.cpp
View file

@ -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>()();

2
src/proc/play/timings.hpp
View file

@ -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

2
tests/library/opaque-holder-test.cpp
View file

@ -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)
*/

BIN
wiki/draw/LumiLogo-small.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.6 KiB

BIN
wiki/draw/LumiLogo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 28 KiB