From 8ba035b2658af2de67c901ab146a7de2f0a3cb0b Mon Sep 17 00:00:00 2001
From: Ben Huber
Date: Tue, 30 May 2017 02:04:54 +0200
Subject: [PATCH] a word about thrad safety; linking to first entry in doxygen
if there are multiple; some more link fixes
---
doc/doxygen/Doxyfile | 2 +-
doc/jekyll/_posts/2000-11-30-tensor.md | 10 ++++++++++
doc/jekyll/documentation.md | 22 +++++++++++-----------
doc/jekyll/index.md | 6 +++---
src/docHelper/parseDoxytags.cpp | 2 +-
5 files changed, 26 insertions(+), 16 deletions(-)
diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile
index faa3a8e..fde9100 100644
--- a/doc/doxygen/Doxyfile
+++ b/doc/doxygen/Doxyfile
@@ -740,7 +740,7 @@ WARN_IF_DOC_ERROR = YES
# parameter documentation, but not about the absence of documentation.
# The default value is: NO.
-WARN_NO_PARAMDOC = YES
+WARN_NO_PARAMDOC = NO
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
diff --git a/doc/jekyll/_posts/2000-11-30-tensor.md b/doc/jekyll/_posts/2000-11-30-tensor.md
index 387c2c2..18ec057 100644
--- a/doc/jekyll/_posts/2000-11-30-tensor.md
+++ b/doc/jekyll/_posts/2000-11-30-tensor.md
@@ -549,3 +549,13 @@ for the following functions (c++ only):
* [.has_factor()](__doxyref(xerus::Tensor::has_factor)) and [.apply_factor()](__doxyref(xerus::Tensor::apply_factor))
* [.get_dense_data()](__doxyref(xerus::Tensor::get_dense_data)); [.get_unsanitized_dense_data()](__doxyref(xerus::Tensor::get_unsanitized_dense_data)); [.get_internal_dense_data()](__doxyref(xerus::Tensor::get_internal_dense_data))
* [.get_sparse_data()](__doxyref(xerus::Tensor::get_sparse_data)); [.get_unsanitized_sparse_data()](__doxyref(xerus::Tensor::get_unsanitized_sparse_data)); [.get_internal_sparse_data()](__doxyref(xerus::Tensor::get_internal_sparse_data))
+
+__warnStart
+
+A note about **thread safety**: accessing different Tensor objects at the same time is always safe - even if the underlying
+data structure is shared. The same can not be said about accessing the same object though. Depending on the [sparsityFactor](__doxyref(xerus::Tensor::sparsityFactor))
+even an access via the [operator[]](__doxyref(xerus::Tensor::operator[])) can lead to a change in internal representation. If
+you really have to read from the same Tensor object from several threads, make sure only to use non-modifying functions (eg. by
+accessing the Tensor only via a `const` reference).
+
+__warnEnd
diff --git a/doc/jekyll/documentation.md b/doc/jekyll/documentation.md
index 69568a0..684789e 100644
--- a/doc/jekyll/documentation.md
+++ b/doc/jekyll/documentation.md
@@ -12,24 +12,24 @@ This Documentation is still **work in progress**. Several Sections are currently
__warnEnd
This is the semi-complete documentation of the `xerus` library. It does not provide you with precise function declarations or
-class hierarchies (check out the [doxygen documentation](doxygen) for those) but instead focuses on small working code snippets
+class hierarchies (check out the [doxygen documentation](/doxygen) for those) but instead focuses on small working code snippets
to demonstrate `xerus`'s capabilities.
The documentation is categorized into chapters that each focus on individual features of the library. In particular the chapters in the "Basic
Usage" section only build upon the knowledge of the previous chapters so that they can easily be read in order. They are still
useful as lookup resources later on though.
-If you have not already done so, you will most likely want to start by downloading and [building xerus](building_xerus). If
-you are uncertain or confused by our nomenclature at any point you can reference the [nomenclature](nomenclature) chapter which
+If you have not already done so, you will most likely want to start by downloading and [building xerus](/building_xerus). If
+you are uncertain or confused by our nomenclature at any point you can reference the [nomenclature](/nomenclature) chapter which
should hopefully allow you to deduce the meaning of all tensor specific terms we use.
-The "Basic Usage" section starts out with the creation and modification of (sparse or dense) tensors ([The Tensor Class](tensor)),
-how to use them in indexed equations to denote contractions, summations etc. ([Indices and Equations](indices)) and finally
-how to denote generalizations of matrix decompositions ([Decompositions and Solve](decompositions)) before explainig any more
-elaborate tensor format. The focus of `xerus` so far clearly lies on the Tensor Train decomposition ([TT-Tensors](tttensors)) and
-algorithms for those to solve least squares problems ([Alternating Algorithms](als), [Riemannian Algorithms](riemannian)) or
-tensor recovery and completion problems ([Tensor Completion / Recovery](completion)). It is possible to use `xerus`'s capabilities
-to construct and contract arbitrary tensor networks though ([General Tensor Networks](tensornetworks)).
+The "Basic Usage" section starts out with the creation and modification of (sparse or dense) tensors ([The Tensor Class](/tensor)),
+how to use them in indexed equations to denote contractions, summations etc. ([Indices and Equations](/indices)) and finally
+how to denote generalizations of matrix decompositions ([Decompositions and Solve](/decompositions)) before explainig any more
+elaborate tensor format. The focus of `xerus` so far clearly lies on the Tensor Train decomposition ([TT-Tensors](/tttensors)) and
+algorithms for those to solve least squares problems ([Alternating Algorithms](/als), [Riemannian Algorithms](/riemannian)) or
+tensor recovery and completion problems ([Tensor Completion / Recovery](/completion)). It is possible to use `xerus`'s capabilities
+to construct and contract arbitrary tensor networks though ([General Tensor Networks](/tensornetworks)).
In the "Advanced Usage" section you find instructions on how to optimize your usage of the `xerus` library to gain those last
-10-20% of speedup ([Optimization](optimization)) and explanations of the debugging tools that `xerus` gives you ([Debugging](debugging)).
+10-20% of speedup ([Optimization](/optimization)) and explanations of the debugging tools that `xerus` gives you ([Debugging](/debugging)).
diff --git a/doc/jekyll/index.md b/doc/jekyll/index.md
index f08a71f..e05994a 100644
--- a/doc/jekyll/index.md
+++ b/doc/jekyll/index.md
@@ -32,13 +32,13 @@ The key features include:
## Getting Started
`xerus` can be obtained via [git](https://git.hemio.de/xerus/xerus) or as an archived download via the same link.
-To build and install the library you might want to check our the [Building xerus](building_xerus) guide.
+To build and install the library you might want to check our the [Building xerus](/building_xerus) guide.
Where to go from there depends on what you want to do with `xerus` and how you learn. You can quickly get a feeling for the library
-by checking out one of the simpler examples like [QTT](quickstart). For most people the more elaborate [documentation](documentation)
+by checking out one of the simpler examples like [QTT](/quickstart). For most people the more elaborate [documentation](/documentation)
will likely be the place to start though. Apart from the basic usage it also explains the mindset behind many design choices and
so is adviced reading material regardless of how deep you want to delve into the library. Finally for the most hardcore developers
-out there, there is an elaborate [doxygen documentation](doxygen).
+out there, there is an elaborate [doxygen documentation](/doxygen).
## Issues
diff --git a/src/docHelper/parseDoxytags.cpp b/src/docHelper/parseDoxytags.cpp
index b29fba8..3a4bacf 100644
--- a/src/docHelper/parseDoxytags.cpp
+++ b/src/docHelper/parseDoxytags.cpp
@@ -41,7 +41,7 @@ int main() {
name = currNamespace+"::"+name;
}
boost::replace_all(name, " ", "");
- tags[name] = anchorfile + '#' + anchor;
+ tags.insert({name, anchorfile + '#' + anchor});
} else {
// std::cout << "* skipping " << subc.first << std::endl;
}
--
GitLab