From 54e09312412c8b52f174badb82084b23c5ef4f7a Mon Sep 17 00:00:00 2001
From: ralfulrich <ralf.ulrich@kit.edu>
Date: Thu, 26 Nov 2020 12:52:28 +0100
Subject: [PATCH] doxygen docu
---
corsika/detail/framework/core/Cascade.inl | 3 --
.../framework/geometry/CoordinateSystem.inl | 1 +
.../detail/framework/random/RNGManager.inl | 2 +-
.../framework/geometry/CoordinateSystem.hpp | 29 +++++++++----
corsika/framework/geometry/FourVector.hpp | 43 ++++++++++---------
corsika/framework/geometry/Point.hpp | 4 +-
corsika/framework/geometry/Vector.hpp | 11 ++---
corsika/framework/random/RNGManager.hpp | 2 +-
corsika/framework/utility/COMBoost.hpp | 2 +-
documentation/Doxyfile.in | 12 ++++++
10 files changed, 67 insertions(+), 42 deletions(-)
diff --git a/corsika/detail/framework/core/Cascade.inl b/corsika/detail/framework/core/Cascade.inl
index 8024b83dd..6fc0a88aa 100644
--- a/corsika/detail/framework/core/Cascade.inl
+++ b/corsika/detail/framework/core/Cascade.inl
@@ -27,9 +27,6 @@
#include <limits>
#include <type_traits>
-/**
- * The cascade namespace assembles all objects needed to simulate full particles cascades.
- */
namespace corsika {
diff --git a/corsika/detail/framework/geometry/CoordinateSystem.inl b/corsika/detail/framework/geometry/CoordinateSystem.inl
index ce5aa9e93..8483a248c 100644
--- a/corsika/detail/framework/geometry/CoordinateSystem.inl
+++ b/corsika/detail/framework/geometry/CoordinateSystem.inl
@@ -10,6 +10,7 @@
#pragma once
+#include <corsika/framework/geometry/RootCoordinateSystem.hpp>
#include <corsika/framework/geometry/QuantityVector.hpp>
#include <corsika/framework/core/PhysicalUnits.hpp>
diff --git a/corsika/detail/framework/random/RNGManager.inl b/corsika/detail/framework/random/RNGManager.inl
index dec9c8493..8ddcb851f 100644
--- a/corsika/detail/framework/random/RNGManager.inl
+++ b/corsika/detail/framework/random/RNGManager.inl
@@ -56,7 +56,7 @@ namespace corsika {
std::vector<std::uint32_t> seeds(1);
sseq.generate(seeds.begin(), seeds.end());
std::uint32_t seed = seeds[0];
- C8LOG_TRACE("Random seed stream {} seed {}", entry.first, seed);
+ CORSIKA_LOG_TRACE("Random seed stream {} seed {}", entry.first, seed);
entry.second.seed(seed);
}
}
diff --git a/corsika/framework/geometry/CoordinateSystem.hpp b/corsika/framework/geometry/CoordinateSystem.hpp
index 45d34e699..32b4c0a8a 100644
--- a/corsika/framework/geometry/CoordinateSystem.hpp
+++ b/corsika/framework/geometry/CoordinateSystem.hpp
@@ -8,6 +8,10 @@ n/*
#pragma once
+/**
+ * \file CoordinateSystem.hpp
+ **/
+
#include <corsika/framework/core/PhysicalUnits.hpp>
#include <corsika/framework/geometry/QuantityVector.hpp>
#include <corsika/framework/logging/Logging.hpp>
@@ -30,24 +34,33 @@ namespace corsika {
*/
using CoordinateSystemPtr = std::shared_ptr<CoordinateSystem const>;
- class RootCoordinateSystem; // fwd decl
- static CoordinateSystemPtr get_root_CoordinateSystem(); // fwd decl
+ /// this is the only way to create ONE unique root CS
+ static CoordinateSystemPtr get_root_CoordinateSystem();
+ /**
+ * Creates new CoordinateSystemPtr by translation along \a vector
+ */
inline CoordinateSystemPtr make_translation(CoordinateSystemPtr const& cs,
QuantityVector<length_d> const& vector);
/**
- * creates a new CS in which vVec points in direction of the new z-axis, \a vVec
+ * creates a new CoordinateSystem in which vVec points in direction of the new z-axis, \a vVec
*/
template <typename TDim>
inline CoordinateSystemPtr make_rotationToZ(CoordinateSystemPtr const& cs,
Vector<TDim> const& vVec);
+ /**
+ * creates a new CoordinateSystem, rotated around axis by angle.
+ */
template <typename TDim>
inline CoordinateSystemPtr make_rotation(CoordinateSystemPtr const& cs,
QuantityVector<TDim> const& axis,
double const angle);
+ /**
+ * creates a new CoordinateSystem, translated by \a translation and rotated around \a axis by \a angle.
+ */
template <typename TDim>
inline CoordinateSystemPtr make_translationAndRotation(
CoordinateSystemPtr const& cs, QuantityVector<length_d> const& translation,
@@ -60,7 +73,7 @@ namespace corsika {
* to other CoordinateSystems. Thus, the geometric
* transformation between all CoordinateSystems is always known and stored.
*
- * The static (sigleton) function \sa make_root_CoordinateSystem is
+ * The static (singleton) function \ref make_root_CoordinateSystem is
* the only way to create and access the global top-level
* CoordinateSystem obect. CoordinateSystem objects should be
* *abosulte* *only* handled in their form of CoordinateSystemPtr,
@@ -69,8 +82,8 @@ namespace corsika {
*
* Thus, new CoordinateSystem are only be created (via
* CoordinateSystemPtr) by transforing existing CoordinateSystem
- * using: \sa rotateToZ, \sa rotate, or \sa translateAndRotate, see
- * below.
+ * using: \ref make_rotationToZ, \ref make_rotation, or \ref
+ * make_translationAndRotation, see below.
*
* Warning: As a consequence, never try to access, modify, copy, the raw
* CoordinateSystem objects directly, this will almost certainly result in undefined
@@ -117,11 +130,11 @@ namespace corsika {
static CoordinateSystem createCS() { return CoordinateSystem(); }
/**
- * \defgroup manipulation and creation function
+ * \name Friends
+ * Manipulation and creation functions.
* \{
**/
- /** this is the only way to create ONE unique root CS **/
friend CoordinateSystemPtr get_root_CoordinateSystem();
friend CoordinateSystemPtr make_translation(CoordinateSystemPtr const& cs,
diff --git a/corsika/framework/geometry/FourVector.hpp b/corsika/framework/geometry/FourVector.hpp
index 4f4bea4de..860d730b8 100644
--- a/corsika/framework/geometry/FourVector.hpp
+++ b/corsika/framework/geometry/FourVector.hpp
@@ -15,6 +15,8 @@
namespace corsika {
/**
+ Description of physical four-vectors
+
FourVector fully supports units, e.g. E in [GeV/c] and p in [GeV],
or also t in [s] and r in [m], etc.
@@ -26,9 +28,9 @@ namespace corsika {
[E/c]=[p].
- The FourVector can return NormSqr and Norm, whereas Norm is
- sqrt(abs(NormSqr)). The physical units are always calculated and
- returned properly.
+ The FourVector can return its squared-norm \ref getNormSqr and its
+ norm \ref getNorm, whereas norm is sqrt(abs(norm-squared)). The
+ physical units are always calculated and returned properly.
FourVector can also return if it is TimeLike, SpaceLike or PhotonLike.
@@ -47,7 +49,7 @@ namespace corsika {
using space_type = typename space_vec_type::quantity_type;
using time_type = typename std::decay<TTimeType>::type;
- //! check the types and the physical units here:
+ // check the types and the physical units here:
static_assert(std::is_same<time_type, space_type>::value ||
std::is_same<time_type, decltype(std::declval<space_type>() /
meter * second)>::value,
@@ -65,7 +67,7 @@ namespace corsika {
FourVector(FourVector const&) = default;
FourVector& operator=(const FourVector&) = default;
~FourVector() = default;
-
+
FourVector(TTimeType const& eT, TSpaceVecType const& eS)
: timeLike_(eT)
, spaceLike_(eS) {}
@@ -90,28 +92,29 @@ namespace corsika {
/**
*
- * @return $p_0^2 - \vec{p}^2$
+ * @return \f$p_0^2 - \vec{p}^2\f$
*/
norm_square_type getNormSqr() const;
/**
*
- * @return $sqrt(p_0^2 - \vec{p}^2)$
+ * @return \f$\sqrt(p_0^2 - \vec{p}^2)\f$
*/
norm_type getNorm() const;
- /*
- * FIXME: a better alternative would be to define an enumeration
+ /**
+ * \todo FIXME: a better alternative would be to define an enumeration
* enum { SpaceLike =-1, TimeLike, LightLike } V4R_Category;
- * and a method called V4R_Category GetCategory() const;
- *
+ * and a method called V4R_Category GetCategory() const;
* RU: then you have to decide in the constructor which avoids "lazyness"
- */
+ **/
+ ///\return if \f$|p_0|>|\vec{p}|\f$
bool isTimelike() const;
+ ///\return if \f$|p_0|<|\vec{p}|\f$
bool isSpacelike() const;
/**
- * @defgroup math operators (class members)
+ * \name Math operators (class members)
* @{
*/
FourVector& operator+=(FourVector const&);
@@ -133,23 +136,21 @@ namespace corsika {
/** @} */
protected:
- //! the data members
+ // the data members
TTimeType timeLike_;
TSpaceVecType spaceLike_;
/**
- * @defgroup the friends: (free) math operators
- * @{
- *
+ * \name Free math operators
* We need to define them inline here since we do not want to
* implement them as template functions. They are valid only for
* the specific types as defined right here.
*
- *
- * Note, these are "free function" (event if they don't look as
+ * Note, these are "free function" (even if they don't look as
* such). Thus, even if the input object uses internal references
* for storage, the free math operators, of course, must provide
* value-copies.
+ * @{
*
**/
friend FourVector<time_type, space_vec_type> operator+(FourVector const& a,
@@ -189,8 +190,8 @@ namespace corsika {
**/
template <typename TTimeType, typename TSpaceVecType>
- inline std::ostream& operator<<(std::ostream& os,
- corsika::FourVector<TTimeType, TSpaceVecType> const& qv);
+ inline std::ostream& operator<<(
+ std::ostream& os, corsika::FourVector<TTimeType, TSpaceVecType> const& qv);
} // namespace corsika
diff --git a/corsika/framework/geometry/Point.hpp b/corsika/framework/geometry/Point.hpp
index c302d14c8..82d783212 100644
--- a/corsika/framework/geometry/Point.hpp
+++ b/corsika/framework/geometry/Point.hpp
@@ -47,7 +47,7 @@ namespace corsika {
*
* \returns A reference type QuantityVector&, but be aware, the underlying class data
* is actually transformed to pCS, if needed. Thus, there may be an implicit call to
- * \sa rebase.
+ * \ref rebase.
**/
inline QuantityVector<length_d>& getCoordinates(CoordinateSystemPtr const& pCS);
@@ -58,7 +58,7 @@ namespace corsika {
* Note, if you access components in a different CoordinateSystem
* pCS than the stored data, internally a temporary object will be
* created and destroyed each call. This can be avoided by using
- * \sa rebase first.
+ * \ref rebase first.
**/
inline LengthType getX(CoordinateSystemPtr const& pCS) const;
inline LengthType getY(CoordinateSystemPtr const& pCS) const;
diff --git a/corsika/framework/geometry/Vector.hpp b/corsika/framework/geometry/Vector.hpp
index 83ea39dcf..ddc0738f5 100644
--- a/corsika/framework/geometry/Vector.hpp
+++ b/corsika/framework/geometry/Vector.hpp
@@ -59,20 +59,21 @@ namespace corsika {
/**
* this always returns a QuantityVector as triple
*
- * \returns A reference type QuantityVector&, but be aware, the underlying class data
+ * \return A reference type QuantityVector&, but be aware, the underlying class data
* is actually transformed to pCS, if needed. Thus, there may be an implicit call to
- * \sa rebase.
+ * \ref rebase.
**/
inline QuantityVector<TDimension>& getComponents(CoordinateSystemPtr const& pCS);
/**
- * \defgroup access coordinate components
- * \{
+ * \name Access coordinate components
*
* Note, if you access components in a different CoordinateSystem
* pCS than the stored data, internally a temporary object will be
* created and destroyed each call. This can be avoided by using
- * \sa rebase first.
+ * \ref rebase first.
+ *
+ * \{
**/
inline quantity_type getX(CoordinateSystemPtr const& pCS) const;
diff --git a/corsika/framework/random/RNGManager.hpp b/corsika/framework/random/RNGManager.hpp
index 163489842..adea23378 100644
--- a/corsika/framework/random/RNGManager.hpp
+++ b/corsika/framework/random/RNGManager.hpp
@@ -14,7 +14,7 @@
#include <string>
#include <corsika/framework/utility/Singleton.hpp>
-#include <corsika/framework/logging/Logging.h>
+#include <corsika/framework/logging/Logging.hpp>
/*!
diff --git a/corsika/framework/utility/COMBoost.hpp b/corsika/framework/utility/COMBoost.hpp
index 85f11d53d..31644cd9a 100644
--- a/corsika/framework/utility/COMBoost.hpp
+++ b/corsika/framework/utility/COMBoost.hpp
@@ -19,7 +19,7 @@ namespace corsika {
/**
This utility class handles Lorentz boost between different
- referenence frames, using FourVectors.
+ referenence frames, using FourVector.
*/
class COMBoost {
diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in
index 0c7e5ca2f..1378999e9 100644
--- a/documentation/Doxyfile.in
+++ b/documentation/Doxyfile.in
@@ -1,5 +1,6 @@
PROJECT_NAME = CORSIKA 8
PROJECT_NUMBER = 0.0.0
+PROJECT_BRIEF = "The framework to simulate particle cascades for astroparticle physics"
GENERATE_HTML = YES
GENERATE_LATEX = YES
@@ -29,6 +30,17 @@ INCLUDE_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
GENERATE_LEGEND = YES
+
USE_MATHJAX = YES
+MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols
+
+#JAVADOC_BANNER = YES
+JAVADOC_AUTOBRIEF = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF = YES
+MULTILINE_CPP_IS_BRIEF = YES
+MARKDOWN_SUPPORT = YES
+BUILTIN_STL_SUPPORT = YES
+CLANG_ASSISTED_PARSING = YES
SEARCHENGINE = YES
--
GitLab