From 08a7ef5327f12c977a863b8a1e1cbea793761a9d Mon Sep 17 00:00:00 2001
From: ralfulrich <ralf.ulrich@kit.edu>
Date: Tue, 29 Jan 2019 11:33:15 +0100
Subject: [PATCH] documentation
---
Framework/StackInterface/CMakeLists.txt | 2 +-
Framework/StackInterface/ParticleBase.h | 36 ++++++++++++-------
Framework/StackInterface/Stack.dox | 3 +-
Framework/StackInterface/Stack.h | 24 ++++++++-----
...ackIterator.h => StackIteratorInterface.h} | 10 +++---
corsika.dox | 3 +-
6 files changed, 50 insertions(+), 28 deletions(-)
rename Framework/StackInterface/{StackIterator.h => StackIteratorInterface.h} (98%)
diff --git a/Framework/StackInterface/CMakeLists.txt b/Framework/StackInterface/CMakeLists.txt
index c6106121..6fce751d 100644
--- a/Framework/StackInterface/CMakeLists.txt
+++ b/Framework/StackInterface/CMakeLists.txt
@@ -1,7 +1,7 @@
set (
CORSIKAstackinterface_HEADERS
Stack.h
- StackIterator.h
+ StackIteratorInterface.h
ParticleBase.h
)
diff --git a/Framework/StackInterface/ParticleBase.h b/Framework/StackInterface/ParticleBase.h
index 72e492c1..752164dc 100644
--- a/Framework/StackInterface/ParticleBase.h
+++ b/Framework/StackInterface/ParticleBase.h
@@ -16,11 +16,8 @@ class StackData; // forward decl
namespace corsika::stack {
- // template <typename> class PI;// : public ParticleBase<StackIteratorInterface> {
- // template <typename, template <typename> typename> class Stack; // forward decl
-
/**
- \class ParticleBase
+ @class ParticleBase
The base class to define the readout of particle properties from a
particle stack. Every stack must implement this readout via the
@@ -34,6 +31,7 @@ namespace corsika::stack {
ParticleBase() = default;
private:
+ // those copy constructors and assigments should never be implemented
ParticleBase(ParticleBase&) = delete;
ParticleBase operator=(ParticleBase&) = delete;
ParticleBase(ParticleBase&&) = delete;
@@ -42,30 +40,44 @@ namespace corsika::stack {
ParticleBase operator=(const ParticleBase&) = delete;
public:
- /// delete this particle on the stack. The corresponding iterator
- /// will be invalidated by this operation
+ /** delete this particle on the stack. The corresponding iterator
+ * will be invalidated by this operation
+ */
void Delete() { GetIterator().GetStack().Delete(GetIterator()); }
+ /**
+ * Add a secondary particle based on *this on the stack @param
+ * args is a variadic list of input data that has to match the
+ * function description in the user defined ParticleInterface::AddSecondary(...)
+ */
template <typename... Args>
- StackIterator AddSecondary(const Args... v) {
- return GetStack().AddSecondary(GetIterator(), v...);
+ StackIterator AddSecondary(const Args... args) {
+ return GetStack().AddSecondary(GetIterator(), args...);
}
- // protected: // todo should be proteced, but don't now how to 'friend Stack'
- /// Function to provide CRTP access to inheriting class (type)
+ // protected: // todo should [MAY]be proteced, but don't now how to 'friend Stack'
+ // Function to provide CRTP access to inheriting class (type)
+ /**
+ * return the corresponding StackIterator for this particle
+ */
StackIterator& GetIterator() { return static_cast<StackIterator&>(*this); }
const StackIterator& GetIterator() const {
return static_cast<const StackIterator&>(*this);
}
protected:
- /// access to underling stack data
+ /** @name Access to underlying stack data
+ @{
+ */
auto& GetStackData() { return GetIterator().GetStackData(); }
const auto& GetStackData() const { return GetIterator().GetStackData(); }
auto& GetStack() { return GetIterator().GetStack(); }
const auto& GetStack() const { return GetIterator().GetStack(); }
+ ///@}
- /// return the index number of the underlying iterator object
+ /**
+ * return the index number of the underlying iterator object
+ */
int GetIndex() const { return GetIterator().GetIndex(); }
};
diff --git a/Framework/StackInterface/Stack.dox b/Framework/StackInterface/Stack.dox
index d051a85a..94aea674 100644
--- a/Framework/StackInterface/Stack.dox
+++ b/Framework/StackInterface/Stack.dox
@@ -13,7 +13,8 @@
\endverbatim
+ All functionality and algorithms for stack data access is located in the namespace corsika::stack
- The minimal example of how to use this is shown in stack_example.cc
+ The minimal example of how to use this is shown in stack_example.cc
*/
\ No newline at end of file
diff --git a/Framework/StackInterface/Stack.h b/Framework/StackInterface/Stack.h
index fdccc205..91d671f5 100644
--- a/Framework/StackInterface/Stack.h
+++ b/Framework/StackInterface/Stack.h
@@ -12,7 +12,7 @@
#ifndef _include_Stack_h__
#define _include_Stack_h__
-#include <corsika/stack/StackIterator.h> // include here, to help application programmres
+#include <corsika/stack/StackIteratorInterface.h>
#include <stdexcept>
@@ -22,8 +22,16 @@
namespace corsika::stack {
+ /**
+ This is just a forward declatation for the user-defined
+ ParticleInterface, which is one of the essential template
+ parameters for the Stack.
+
+ Important: ParticleInterface must inherit from ParticleBase !
+ */
+
template <typename>
- class PI; // forward decl
+ class ParticleInterface; // forward decl
/**
Interface definition of a Stack object. The Stack implements the
@@ -31,17 +39,17 @@ namespace corsika::stack {
loops etc.
*/
- template <typename StackData, template <typename> typename PI>
+ template <typename StackData, template <typename> typename ParticleInterface>
class Stack : public StackData {
public:
- typedef Stack<StackData, PI> StackType;
- typedef StackIteratorInterface<StackData, PI> StackIterator;
- typedef ConstStackIteratorInterface<StackData, PI> ConstStackIterator;
+ typedef Stack<StackData, ParticleInterface> StackType;
+ typedef StackIteratorInterface<StackData, ParticleInterface> StackIterator;
+ typedef ConstStackIteratorInterface<StackData, ParticleInterface> ConstStackIterator;
// typedef const StackIterator ConstStackIterator;
typedef typename StackIterator::ParticleInterfaceType ParticleType;
- friend class StackIteratorInterface<StackData, PI>;
- friend class ConstStackIteratorInterface<StackData, PI>;
+ friend class StackIteratorInterface<StackData, ParticleInterface>;
+ friend class ConstStackIteratorInterface<StackData, ParticleInterface>;
public:
using StackData::GetCapacity;
diff --git a/Framework/StackInterface/StackIterator.h b/Framework/StackInterface/StackIteratorInterface.h
similarity index 98%
rename from Framework/StackInterface/StackIterator.h
rename to Framework/StackInterface/StackIteratorInterface.h
index c960fced..7ac72c34 100644
--- a/Framework/StackInterface/StackIterator.h
+++ b/Framework/StackInterface/StackIteratorInterface.h
@@ -9,8 +9,8 @@
* the license.
*/
-#ifndef _include_StackIterator_h__
-#define _include_StackIterator_h__
+#ifndef _include_StackIteratorinterface_h__
+#define _include_StackIteratorinterface_h__
#include <corsika/stack/ParticleBase.h>
@@ -112,9 +112,9 @@ namespace corsika::stack {
}
public:
- /** @name Iterator interface
- */
- ///@{
+ /** @name Iterator interface
+ @{
+ */
StackIteratorInterface& operator++() {
++fIndex;
return *this;
diff --git a/corsika.dox b/corsika.dox
index 3447fcc5..b84d0e9e 100644
--- a/corsika.dox
+++ b/corsika.dox
@@ -1,5 +1,6 @@
/**
-@mainpage CORSIKA air shower simulations framework
+
+@mainpage CORSIKA 8 air shower simulations framework
Documentation and reference guide for the CORSIKA8 (CORSIKA version 8)
software framework for air shower simulations. CORSIKA8 is developed
--
GitLab