more doc

src/include/ranges/crange.h

@@ -21,7 +21,7 @@
 namespace CNORXZ
 {
     /** ****
-	specific index for CRange
+	Specific index for CRange.
      */
     class CIndex : public IndexInterface<CIndex,SizeT>
     {
@@ -34,7 +34,7 @@ namespace CNORXZ
 	INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
 	DEFAULT_MEMBERS(CIndex); /**< default constructors and assignments */
 
-	/** constrcut index from range and position
+	/** Construct index from range and position.
 	    @param range Range to iterate over
 	    @param pos lexicographic position
 	 */
@@ -98,9 +98,6 @@ namespace CNORXZ
 	/** @copydoc IndexInterface::at() */
 	CIndex& at(const SizeT& metaPos);
 
-	/** @copydoc IndexInterface::xpr() */
-	COpRoot<SizeT,CIndex> xpr(const Sptr<CIndex>& _this) const;
-
 	/** @copydoc IndexInterface::prange() */
 	RangePtr prange(const CIndex& last) const;
 
@@ -120,6 +117,9 @@ namespace CNORXZ
 	/** @copydoc IndexInterface::formatIsTrivial() */
 	bool formatIsTrivial() const;
 	
+	/** @copydoc IndexInterface::xpr() */
+	COpRoot<SizeT,CIndex> xpr(const Sptr<CIndex>& _this) const;
+
     private:
 	Sptr<RangeType> mRangePtr;
     };

src/include/ranges/dindex.cc.h

@@ -44,7 +44,9 @@ namespace CNORXZ
     I indexAs(const DIndex& i)
     {
 	static_assert(is_index<I>::value, "expected index type");
-	return std::dynamic_pointer_cast<XIndex<I,typename I::MetaType>>( i.xptr() )->get();
+	auto ptr = std::dynamic_pointer_cast<XIndex<I,typename I::MetaType>>( i.xptr() );
+	CXZ_ASSERT(ptr, "invalid cast");
+	return ptr->get();
     }
 }
 

src/include/ranges/dindex.h

@@ -20,6 +20,9 @@
 
 namespace CNORXZ
 {
+    /** ****
+	index of compile-time-unspecified type
+     */
     class DIndex : public IndexInterface<DIndex,DType>
     {
     public:
@@ -27,64 +30,145 @@ namespace CNORXZ
 	typedef DType MetaType;
 	typedef RangeBase RangeType;
 
-	DEFAULT_C(DIndex);
+	DEFAULT_C(DIndex); /**< default constructor */
+
+	/** copy constructor
+	    @param i index to copy
+	 */
 	DIndex(const DIndex& i);
+
+	/** move constructor
+	    @param i index to move
+	 */
 	DIndex(DIndex&& i);
+
+	/** copy assignment
+	    @param i index to copy 
+	 */
 	DIndex& operator=(const DIndex& i);
+
+	/** move assignment
+	    @param i index to move
+	 */
 	DIndex& operator=(DIndex&& i);
+
+	/** construct from XIndex instance
+	    @param i XIndex to use for construction
+	 */
 	DIndex(const XIndexPtr& i);
+
+	/** construct from range pointer
+	    @param r Range to iterate over
+	    @param lexpos initial lexicographic position
+	 */
 	DIndex(const RangePtr& r, SizeT lexpos = 0);
-	
+
+	/** construct from index of arbitrary type
+	    @param i Index to use for construction 
+	 */
 	template <class Index, typename Meta>
 	DIndex(const IndexInterface<Index,Meta>& i);
 
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	DIndex& operator=(SizeT lexpos);
+
+	/** @copydoc IndexInterface::operator++() */
 	DIndex& operator++();
+
+	/** @copydoc IndexInterface::operator--() */
 	DIndex& operator--();
+
+	/** @copydoc IndexInterface::operator+() */
 	DIndex operator+(Int n) const;
+
+	/** @copydoc IndexInterface::operator-() */
 	DIndex operator-(Int n) const;
+
+	/** @copydoc IndexInterface::operator-(CIndex) */
 	SizeT operator-(const DIndex& i) const;
+
+	/** @copydoc IndexInterface::operator+=() */
 	DIndex& operator+=(Int n);
+
+	/** @copydoc IndexInterface::operator-=() */
 	DIndex& operator-=(Int n);
 
+	/** @copydoc IndexInterface::lex() */
 	SizeT lex() const;
+
+	/** @copydoc IndexInterface::pmax() */
 	UPos pmax() const;
+
+	/** @copydoc IndexInterface::lmax() */
 	UPos lmax() const;
+
+	/** @copydoc IndexInterface::id() */
 	IndexId<0> id() const;
 	
+	/** @copydoc IndexInterface::operator*() */
 	DType operator*() const;
 
+	/** @copydoc IndexInterface::dim() */
 	SizeT dim() const;
+
+	/** @copydoc IndexInterface::range() */
 	RangePtr range() const;
 
+	/** @copydoc IndexInterface::stepSize() */
 	UPos stepSize(const IndexId<0>& id) const;
 
+	/** @copydoc IndexInterface::stringMeta() */
 	String stringMeta() const;
+
+	/** @copydoc IndexInterface::meta() */
 	DType meta() const;
+
+	/** @copydoc IndexInterface::at() */
 	DIndex& at(const DType& meta);
+
+	/** @copydoc IndexInterface::prange() */
 	RangePtr prange(const DIndex& end) const;
+
+	/** @copydoc IndexInterface::deepFormat() */
 	Vector<SizeT> deepFormat() const;
+
+	/** @copydoc IndexInterface::deepMax() */
 	Vector<SizeT> deepMax() const;
 
 	/** @copydoc IndexInterface::reformat() */
 	DIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
 	
+	/** @copydoc IndexInterface::ifor() */
 	template <class Xpr, class F>
 	decltype(auto) ifor(const Xpr& xpr, F&& f) const;
 	
-	const XIndexPtr& xptr() const;
-
 	/** @copydoc IndexInterface::formatIsTrivial() */
 	bool formatIsTrivial() const;
 
+	/** get internal XIndex instance
+	    @return shared pointer to XIndex instance
+	 */
+	const XIndexPtr& xptr() const;
+
     private:
 	XIndexPtr mI;
     };
 
+    /** Trait-specialization:
+	DIndex can have sub-indices
+     */
     template <>
     struct has_sub<DIndex>
     { static constexpr bool value = true; };
 
+    /** dynamically cast DIndex to given type.
+	If type does not match the index type of the underlying index
+	and exception is thrown
+
+	@tparam I index type to be returned
+	@param i DIndex to by casted
+	@return copy of underlying index instance
+     */
     template <class I>
     I indexAs(const DIndex& i);
 }

src/include/ranges/index_pack.h

@@ -2,12 +2,17 @@
 /**
    
    @file include/ranges/index_pack.h
-   @brief ...
+   @brief Index pack declaration
 
+   Index packs are sets of indices. In contrast to multi-indices like
+   (G)MIndex or YIndex, there is no format that can be used to determine
+   a linearized memory position. Hence, only a lexicographic position is well defined.
+   Nevertheless, a function pos() is implemented, which just returns
+   the same value as lex().
 
    Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
-   
+
 **/
 
 #ifndef __cxz_index_pack_h__
@@ -18,76 +23,203 @@
 
 namespace CNORXZ
 {
+    /** ****
+	Static index pack.
+	Containes tuple of shared pointers to index instances.
+	@tparam Indices Index types.
+     */
     template <class... Indices>
     class SPack
     {
     public:
-	SP_DEFAULT_MEMBERS(constexpr,SPack);
+	SP_DEFAULT_MEMBERS(constexpr,SPack); /**< default constructors and assignments */
+
+	/** Construct from index pointers
+	    @param is index pointers
+	 */
 	constexpr SPack(const Sptr<Indices>&... is);
+
+	/** Construct from index pointer tuple
+	    @param is index pointer tuple
+	 */
 	constexpr SPack(const Tuple<Sptr<Indices>...>& is);
 
+	/** get underlying index pointer tuple
+	    @return underlying index pointer tuple
+	 */
 	constexpr const Tuple<Sptr<Indices>...>& all() const;
 
+	/** get pack size i.e. dimension (non-recursive)
+	    @return pack size
+	 */
 	constexpr SizeT size() const;
-	
+
+	/** get pack element
+	    @return i'th element of the pack
+	    @tparam I static position
+	    @param i static position instance
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) get(CSizeT<I> i) const;
 
+	/** get pack element
+	    @return i'th element of the pack
+	    @tparam I static position
+	    @param i static position instance
+	 */
 	template <SizeT I>
 	constexpr decltype(auto) operator[](CSizeT<I> i) const;
 
+	/** Append index on the r.h.s. of the pack.
+	    @tparam Index Type of the index to be appended
+	    @param i index to be appended
+	 */
 	template <class Index>
 	constexpr decltype(auto) rmul(const Sptr<Index>& i) const;
 
+	/** Append index on the l.h.s. of the pack.
+	    @tparam Index Type of the index to be appended
+	    @param i Index to be appended
+	 */
 	template <class Index>
 	constexpr decltype(auto) lmul(const Sptr<Index>& i) const;
 
+	/** Append another index pack on the r.h.s. of this pack
+	    @tparam Indices2 Types of the indices in the pack to be appended
+	    @param p Index pack to be appended
+	 */
 	template <class... Indices2>
 	constexpr decltype(auto) mul(const SPack<Indices2...>& p) const;
 
+	/** create a range from the index pack
+	    @return created range
+	 */
 	decltype(auto) mkRange() const;
 
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT lex() const;
+
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT pos() const;
 	
     private:
 	Tuple<Sptr<Indices>...> mIs;
     };
 
+    /** Create static index pack
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     constexpr decltype(auto) spack(const Indices&... inds);
 
+    /** Create static index pack from index pointers
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     constexpr decltype(auto) spackp(const Sptr<Indices>&... inds);
 
+    /** ******
+	Dynamic index pack.
+	Containes array of shared pointers to XIndex instances.
+     */
     class DPack
     {
     public:
-	DEFAULT_MEMBERS(DPack);
+	DEFAULT_MEMBERS(DPack); /**< default constructors and assignments */
+
+	/** Create pack from XIndex instance
+	    @param is Vector of XIndex pointers
+	 */
 	explicit DPack(const Vector<XIndexPtr>& is);
+
+	/** Create pack from XIndex instance (move input vector)
+	    @param is Vector of XIndex pointers
+	 */
 	explicit DPack(Vector<XIndexPtr>&& is);
 
+	/** Create pack from a static pack (SPack)
+	    @param p static pack used for construction
+	 */
 	template <class... Indices>
 	explicit DPack(const SPack<Indices...>& p);
-	
+
+	/** get underlying index pointer vector
+	    @return underlying index pointer vector
+	 */
 	const Vector<XIndexPtr>& all() const;
+
+	/** get pack size i.e. dimension (non-recursive)
+	    @return pack size
+	 */
 	SizeT size() const;
+
+	/** get pack element
+	    @return i'th element of the pack
+	    @param i Position
+	 */
 	const XIndexPtr& get(SizeT i) const;
+
+	/** get pack element
+	    @return i'th element of the pack
+	    @param i Position
+	 */
 	const XIndexPtr& operator[](SizeT i) const;
+
+	/** Append index on the r.h.s.
+	    @param i DIndex to be appended
+	 */
 	DPack rmul(const Sptr<DIndex>& i) const;
+
+	/** Append index on the l.h.s.
+	    @param i DIndex to be appended
+	 */
 	DPack lmul(const Sptr<DIndex>& i) const;
+
+	/** Append pack on the r.h.s.
+	    @param p Pack to be appnded
+	 */
 	DPack mul(const DPack& p) const;
+
+	/** create a range from the index pack
+	    @return created range
+	 */
 	RangePtr mkRange() const;
+
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT lex() const;
+
+	/** Get lexicographic position if pack was transformed to a (trivial) multi-index.
+	    @return lexicographic position
+	 */
 	SizeT pos() const;
 	
     private:
 	Vector<XIndexPtr> mIs;
     };
 
+    /** Create dynamic index pack
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     DPack dpack(const Indices&... inds);
 
+    /** Create dynamic index pack from index pointers
+	@tparam Indices index types
+	@param inds Indices to create the pack from
+	@return Created pack
+     */
     template <class... Indices>
     DPack dpackp(const Sptr<Indices>&... inds);
 }