ranges: add remaining doxy comments

src/include/ranges/srange.h

@@ -2,10 +2,9 @@
 /**
    
    @file include/ranges/srange.h
-   @brief ...
+   @brief SRange, SRangeFactory and SIndex declaration.
 
-
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -20,6 +19,11 @@
 
 namespace CNORXZ
 {
+    /** ****
+	Specific index for SRange.
+	@tparam MetaT Meta data type.
+	@tparam S Static size of the range.
+     */
     template <typename MetaT, SizeT S>
     class SIndex : public IndexInterface<SIndex<MetaT,S>,MetaT>
     {
@@ -29,43 +33,88 @@ namespace CNORXZ
 	typedef MetaT MetaType;
 
 	INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
-	DEFAULT_MEMBERS(SIndex);
+	DEFAULT_MEMBERS(SIndex); /**< default constructors and assignments */
+
+	/** Construct index from range and position.
+	    @param range Range to iterate over.
+	    @param pos lexicographic position.
+	 */
 	SIndex(const RangePtr& range, SizeT pos = 0);
 
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	SIndex& operator=(SizeT lexpos);
+
+	/** @copydoc IndexInterface::operator++() */
 	SIndex& operator++();
+
+	/** @copydoc IndexInterface::operator--() */
 	SIndex& operator--();
+
+	/** @copydoc IndexInterface::operator+() */
 	SIndex operator+(Int n) const;
+
+	/** @copydoc IndexInterface::operator-() */
 	SIndex operator-(Int n) const;
+
+	/** @copydoc IndexInterface::operator-(SIndex) */
 	SizeT operator-(const SIndex& i) const;
+
+	/** @copydoc IndexInterface::operator+=() */
 	SIndex& operator+=(Int n);
+
+	/** @copydoc IndexInterface::operator-=() */
 	SIndex& operator-=(Int n);
 
+	/** @copydoc IndexInterface::lex() */
 	SizeT lex() const;
+
+	/** @copydoc IndexInterface::pmax() */
 	SPos<S> pmax() const;
+
+	/** @copydoc IndexInterface::lmax() */
 	SPos<S> lmax() const;
+
+	/** @copydoc IndexInterface::id() */
 	IndexId<0> id() const;
 	
+	/** @copydoc IndexInterface::operator*() */
 	const MetaT& operator*() const;
 	
+	/** @copydoc IndexInterface::dim() */
 	SizeT dim() const; // = 1
+
+	/** @copydoc IndexInterface::range() */
 	Sptr<RangeType> range() const;
 
+	/** @copydoc IndexInterface::stepSize() */
 	template <SizeT I>
 	UPos stepSize(const IndexId<I>& id) const;
 
+	/** @copydoc IndexInterface::stringMeta() */
 	String stringMeta() const;
-	const MetaT& meta() const;
-	SIndex& at(const MetaT& metaPos);
-	decltype(auto) xpr(const Sptr<SIndex<MetaType,S>>& _this) const;
 
+	/** @copydoc IndexInterface::meta() */
+	const MetaT& meta() const;
+
+	/** @copydoc IndexInterface::at() */
+	SIndex& at(const MetaT& metaPos);
+
+	/** @copydoc IndexInterface::prange() */
 	RangePtr prange(const SIndex<MetaType,S>& last) const;
+
+	/** @copydoc IndexInterface::deepFormat() */
 	SizeT deepFormat() const;
+
+	/** @copydoc IndexInterface::deepMax() */
 	SizeT deepMax() const;
 
 	/** @copydoc IndexInterface::reformat() */
 	SIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
 
+	/** @copydoc IndexInterface::ifor() */
+	decltype(auto) xpr(const Sptr<SIndex<MetaType,S>>& _this) const;
+
+	/** @copydoc IndexInterface::ifor() */
 	template <class Xpr, class F>
 	decltype(auto) ifor(const Xpr& xpr, F&& f) const;
 
@@ -77,16 +126,43 @@ namespace CNORXZ
 	const MetaT* mMetaPtr;
     };
 
+    /** Make index pack of a SIndex and another index.
+	@param a pointer to SIndex.
+	@param b pointer to another index.
+     */
     template <typename MetaT, SizeT S, class I1>
     decltype(auto) operator*(const Sptr<SIndex<MetaT,S>>& a, const Sptr<I1>& b);
 
+    /** ****
+	Specific factory for SRange.
+	@tparam MetaT Meta data type.
+	@tparam S Static size of the range.
+     */
     template <typename MetaT, SizeT S>
     class SRangeFactory : public RangeFactoryBase
     {
     public:
+
+	/** Construct and setup factory.
+	    @param space Meta data array defining the range. 
+	 */
 	SRangeFactory(const Arr<MetaT,S>& space);
+
+	/** Construct and setup factory.
+	    @param space Meta data array defining the range (move). 
+	 */
         SRangeFactory(Arr<MetaT,S>&& space);
+
+	/** Construct and setup factory.
+	    @param space Meta data array defining the range.
+	    @param ref Range the range to be constructed is related to.
+	 */
 	SRangeFactory(const Arr<MetaT,S>& space, const RangePtr& ref);
+
+	/** Construct and setup factory.
+	    @param space Meta data array defining the range (move).
+	    @param ref Range the range to be constructed is related to.
+	 */
         SRangeFactory(Arr<MetaT,S>&& space, const RangePtr& ref);
 	
     private:
@@ -97,6 +173,12 @@ namespace CNORXZ
 	RangePtr mRef;
     };
 
+    /** ****
+	Static size range.
+	The same as URange, but the range size is compile-time fixed.
+	@tparam MetaT Meta data type.
+	@tparam S Static range size.
+     */
     template <typename MetaT, SizeT S>
     class SRange : public RangeInterface<SRange<MetaT,S>>
     {
@@ -114,8 +196,19 @@ namespace CNORXZ
 	virtual const TypeInfo& metaType() const override final;
 	virtual RangePtr extend(const RangePtr& r) const override final;
 
+	/** return meta data at given position.
+	    @param pos position, size type
+	 */
 	const MetaT& get(SizeT pos) const;
+
+	/** Get underlying meta data array.
+	    @return Pointer to first position of meta data array. 
+	 */
 	const MetaT* get() const;
+
+	/** return position for given meta data.
+	    @param metaPos meta data, size type
+	 */
 	SizeT getMeta(const MetaT& metaPos) const;
 
     private:
@@ -132,9 +225,16 @@ namespace CNORXZ
 	SERIALIZATION_FUNCTIONS_NOPUB;
     };
 
+    /** ***
+	Specialize RangeCast for casts to SRange
+	@see RangeCast
+	@tparam MetaT Meta data type.
+	@tparam S Static range size.
+     */    
     template <typename MetaT, SizeT S>
     struct RangeCast<SRange<MetaT,S>>
     {
+	/** cast the range */
 	static Sptr<SRange<MetaT,S>> func(const RangePtr& r);
     };
     

src/include/ranges/urange.h

@@ -2,10 +2,9 @@
 /**
    
    @file include/ranges/urange.h
-   @brief ...
+   @brief URange, URangeFactory and UIndex declaration.
 
-
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -23,6 +22,10 @@
 namespace CNORXZ
 {
     
+    /** ****
+	Specific index for URange.
+	@tparam MetaT Meta data type.
+     */
     template <typename MetaT>
     class UIndex : public IndexInterface<UIndex<MetaT>,MetaT>
     {
@@ -33,51 +36,94 @@ namespace CNORXZ
 	typedef MetaT MetaType;
 
 	INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
-	DEFAULT_MEMBERS(UIndex);
+	DEFAULT_MEMBERS(UIndex); /**< default constructors and assignments */
+	
+	/** Construct index from range and position.
+	    @param range Range to iterate over.
+	    @param pos lexicographic position.
+	 */
 	UIndex(const RangePtr& range, SizeT pos = 0);
 
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	UIndex& operator=(SizeT lexpos);
+
+	/** @copydoc IndexInterface::operator++() */
 	UIndex& operator++();
+
+	/** @copydoc IndexInterface::operator--() */
 	UIndex& operator--();
+
+	/** @copydoc IndexInterface::operator+() */
 	UIndex operator+(Int n) const;
+
+	/** @copydoc IndexInterface::operator-() */
 	UIndex operator-(Int n) const;
+
+	/** @copydoc IndexInterface::operator-(UIndex) */
 	SizeT operator-(const UIndex& i) const;
+
+	/** @copydoc IndexInterface::operator+=() */
 	UIndex& operator+=(Int n);
+
+	/** @copydoc IndexInterface::operator-=() */
 	UIndex& 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*() */
 	const MetaT& operator*() const;
 	
+	/** @copydoc IndexInterface::dim() */
 	SizeT dim() const; // = 1
+
+	/** @copydoc IndexInterface::range() */
 	Sptr<RangeType> range() const;
 
+	/** @copydoc IndexInterface::stepSize() */
 	template <SizeT I>
 	decltype(auto) stepSize(const IndexId<I>& id) const;
 
+	/** @copydoc IndexInterface::stringMeta() */
 	String stringMeta() const;
-	const MetaT& meta() const;
-	UIndex& at(const MetaT& metaPos);
-	decltype(auto) xpr(const Sptr<UIndex<MetaType>>& _this) const;
 
+	/** @copydoc IndexInterface::meta() */
+	const MetaT& meta() const;
+
+	/** @copydoc IndexInterface::at() */
+	UIndex& at(const MetaT& metaPos);
+
+	/** @copydoc IndexInterface::prange() */
 	RangePtr prange(const UIndex<MetaType>& last) const;
 
+	/** @copydoc IndexInterface::deepFormat() */
 	SizeT deepFormat() const;
 
+	/** @copydoc IndexInterface::deepMax() */
 	SizeT deepMax() const;
-	
+
 	/** @copydoc IndexInterface::reformat() */
 	UIndex& 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;
 
 	/** @copydoc IndexInterface::formatIsTrivial() */
 	bool formatIsTrivial() const;
 
+	/** @copydoc IndexInterface::xpr() */
+	decltype(auto) xpr(const Sptr<UIndex<MetaType>>& _this) const;
+
     private:
 	Sptr<RangeType> mRangePtr;
 	const MetaT* mMetaPtr;
@@ -86,26 +132,39 @@ namespace CNORXZ
     template <typename MetaT>
     void swap(UIndex<MetaT>& a, UIndex<MetaT>& b) { a.swap(b); } 
     
-    template <typename MetaType, class I1>
+    /** Make index pack of a UIndex and another index.
-    decltype(auto) operator*(const Sptr<UIndex<MetaType>>& a, const Sptr<I1>& b);
+	@param a pointer to UIndex.
+	@param b pointer to another index.
+     */
+    template <typename MetaT, class I1>
+    decltype(auto) operator*(const Sptr<UIndex<MetaT>>& a, const Sptr<I1>& b);
     
-    template <typename MetaType>
+    /** ****
+	Specific factory for URange.
+	@tparam MetaT Meta data type.
+     */
+    template <typename MetaT>
     class URangeFactory : public RangeFactoryBase
     {
     public:
-	URangeFactory(const Vector<MetaType>& space);
+	URangeFactory(const Vector<MetaT>& space);
-        URangeFactory(Vector<MetaType>&& space);
+        URangeFactory(Vector<MetaT>&& space);
-	URangeFactory(const Vector<MetaType>& space, const RangePtr& ref);
+	URangeFactory(const Vector<MetaT>& space, const RangePtr& ref);
-        URangeFactory(Vector<MetaType>&& space, const RangePtr& ref);
+        URangeFactory(Vector<MetaT>&& space, const RangePtr& ref);
 	
     private:
 	URangeFactory() = default;
 	virtual void make() override final;
 
-	Vector<MetaType> mSpace;
+	Vector<MetaT> mSpace;
 	RangePtr mRef;
     };
 
+    /** ****
+	Uni-(1-)dimensional range with non-trivial meta data space
+	i.e. the parameter space can be arbitrary.
+	@tparam MetaT Meta data type.
+     */
     template <typename MetaT>
     class URange : public RangeInterface<URange<MetaT>>
     {
@@ -123,8 +182,21 @@ namespace CNORXZ
 	virtual const TypeInfo& metaType() const override final;
 	virtual RangePtr extend(const RangePtr& r) const override final;
 
+	/** Get meta data at given range position.
+	    @param pos Integer indicating requested position.
+	    @return Meta data at given postion.
+	 */
 	const MetaType& get(SizeT pos) const;
+
+	/** Get meta data array.
+	    @return Pointer to first element of the underlying meta data array.
+	 */
 	const MetaType* get() const;
+
+	/** Get range position for given meta data.
+	    @param metaPos Meta data.
+	    @return Position of the given meta data if it is contained by the range.
+	 */
 	SizeT getMeta(const MetaType& metaPos) const;
 	
     private:
@@ -141,12 +213,21 @@ namespace CNORXZ
 	SERIALIZATION_FUNCTIONS_NOPUB;
     };
 
+    /** ***
+	Specialize RangeCast for casts to URange
+	@see RangeCast
+     */    
     template <typename MetaType>
     struct RangeCast<URange<MetaType>>
     {
+	/** cast the range */
 	static Sptr<URange<MetaType>> func(const RangePtr& r);
     };
 
+    /** Create an URange, calls URangeFactory.
+	@param space Meta data space to create an URange on.
+	@return Created range.
+     */
     template <typename MetaT>
     RangePtr urange(const Vector<MetaT>& space);
 

src/include/ranges/xindex.h

@@ -2,10 +2,9 @@
 /**
    
    @file include/ranges/xindex.h
-   @brief ...
+   @brief XIndexBase and XIndex template declaration.
 
-
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/
@@ -20,66 +19,145 @@
 
 namespace CNORXZ
 {
+    /** ****
+	Abstract index wrapper base.
+	Can be used for index polymorphism.
+	Only use if absolutely necessary, indices should always reveal as much as possible
+	to the compiler!
+     */
     class XIndexBase
     {
     public:
 
-	//typedef DType MetaType;
+	DEFAULT_MEMBERS(XIndexBase); /**< default constructors and assignments */
-	
+
-	DEFAULT_MEMBERS(XIndexBase);
+	/** Virtual default destructor */
 	virtual ~XIndexBase() = default;
+
+	/** Copy this index
+	    @return Pointer to the copy.
+	 */
 	virtual XIndexPtr copy() const = 0;
+
+	/** Current position.
+	    @return Current position.
+	 */
 	virtual SizeT pos() const = 0;
 	
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	virtual XIndexBase& operator=(SizeT lexpos) = 0;
+
+	/** @copydoc IndexInterface::operator++() */
 	virtual XIndexBase& operator++() = 0;
+
+	/** @copydoc IndexInterface::operator--() */
 	virtual XIndexBase& operator--() = 0;
+
+	/** @copydoc IndexInterface::operator+() */
 	virtual XIndexPtr operator+(Int n) const = 0;
+
+	/** @copydoc IndexInterface::operator-() */
 	virtual XIndexPtr operator-(Int n) const = 0;
+
+	/** @copydoc IndexInterface::operator-(UIndex) */
 	virtual SizeT operator-(const XIndexBase& i) const = 0;
+
+	/** @copydoc IndexInterface::operator+=() */
 	virtual XIndexBase& operator+=(Int n) = 0;
+
+	/** @copydoc IndexInterface::operator-=() */
 	virtual XIndexBase& operator-=(Int n) = 0;
 
+	/** @copydoc IndexInterface::lex() */
 	virtual SizeT lex() const = 0;
+
+	/** @copydoc IndexInterface::pmax() */
 	virtual UPos pmax() const = 0;
+
+	/** @copydoc IndexInterface::lmax() */
 	virtual UPos lmax() const = 0;
+
+	/** @copydoc IndexInterface::id() */
 	virtual IndexId<0> id() const = 0;
 	
+	/** @copydoc IndexInterface::operator*() */
 	virtual DType operator*() const = 0;
 
+	/** @copydoc IndexInterface::dim() */
 	virtual SizeT dim() const = 0;
-	virtual RangePtr range() const = 0;
-	virtual UPos stepSize(const IndexId<0>& id) const = 0;
-	virtual RangePtr prange(const XIndexPtr& last) const = 0;
-	virtual Vector<SizeT> deepFormat() const = 0;
-	virtual Vector<SizeT> deepMax() const = 0;
-	virtual XIndexBase& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s) = 0;
 
+	/** @copydoc IndexInterface::range() */
+	virtual RangePtr range() const = 0;
+
+	/** @copydoc IndexInterface::stepSize() */
+	virtual UPos stepSize(const IndexId<0>& id) const = 0;
+
+	/** @copydoc IndexInterface::stringMeta() */
 	virtual String stringMeta() const = 0;
+
+	/** @copydoc IndexInterface::meta() */
 	virtual DType meta() const = 0;
+
+	/** @copydoc IndexInterface::at() */
 	virtual XIndexBase& at(const DType& meta) = 0;
 
+	/** @copydoc IndexInterface::prange() */
+	virtual RangePtr prange(const XIndexPtr& last) const = 0;
+
+	/** @copydoc IndexInterface::deepFormat() */
+	virtual Vector<SizeT> deepFormat() const = 0;
+
+	/** @copydoc IndexInterface::deepMax() */
+	virtual Vector<SizeT> deepMax() const = 0;
+
+	/** @copydoc IndexInterface::reformat() */
+	virtual XIndexBase& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s) = 0;
+
+	/** @copydoc IndexInterface::ifor() */
 	virtual DXpr<None> ifor(const DXpr<None>& xpr, NoF&& f) const = 0;
 
+	/** @copydoc IndexInterface::formatIsTrivial() */
 	virtual bool formatIsTrivial() const = 0;
     };
 
-    //Sptr<XIndexBase>& operator++(Sptr<XIndexBase>& i);
+    /** ****
-    //Sptr<XIndexBase>& operator--(Sptr<XIndexBase>& i);
+	Index Wrapper.
-    
+	@tparam Index Type of index to be wrapped.
-    // MultiIndex Wrapper:
+	@tparam Meta Meta data type of wrapped index.
+     */
     template <class Index, typename Meta>
     class XIndex : public XIndexBase
     {
     public:
 
-	DEFAULT_C(XIndex);
+	DEFAULT_C(XIndex); /** < default constructor. */
-	// no default copy/assignment (have to copy objects in shared ptr)
+
+	/** Copy constructor.
+	    No default: have to copy objects in shared ptr.
+	 */
 	XIndex(const XIndex& i);
+
+	/** Move constructor.
+	 */
 	XIndex(XIndex&& i);
+
+	/** Copy assignment.
+	    No default: have to copy objects in shared ptr.
+	 */
 	XIndex& operator=(const XIndex& i);
+
+	/** Move assignment.
+	 */
 	XIndex& operator=(XIndex&& i);
+
+	/** Construct.
+	    @param i Pointer to index to be wrapped.
+	 */
 	XIndex(const IndexPtr<Index,Meta>& i);
+
+	/** Construct.
+	    @param i Index to be wrapped.
+	 */
 	XIndex(const IndexInterface<Index,Meta>& i);
 
 	virtual XIndexPtr copy() const override final;
@@ -104,20 +182,24 @@ namespace CNORXZ
 	virtual SizeT dim() const override final;
 	virtual RangePtr range() const override final;
 	virtual UPos stepSize(const IndexId<0>& id) const override final;
+	virtual String stringMeta() const override final;
+	virtual DType meta() const override final;
+	virtual XIndexBase& at(const DType& meta) override final;
 	virtual RangePtr prange(const XIndexPtr& last) const override final;
 	virtual Vector<SizeT> deepFormat() const override final;
 	virtual Vector<SizeT> deepMax() const override final;
 	virtual XIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s) override final;
-
-	virtual String stringMeta() const override final;
-	virtual DType meta() const override final;
-	virtual XIndexBase& at(const DType& meta) override final;
-
 	virtual DXpr<None> ifor(const DXpr<None>& xpr, NoF&& f) const override final;
-
 	virtual bool formatIsTrivial() const override final;
 
+	/** Get underlying index instance.
+	    @return Reference to index.
+	 */
 	Index& get();
+
+	/** Get underlying index instance (const).
+	    @return Reference to index.
+	 */
 	const Index& get() const;
 
     private:
@@ -125,13 +207,28 @@ namespace CNORXZ
 
     };
 
+    /** ****
+	Specialization: has_sub for XIndexBase.
+	XIndexBase can have sub-indices.
+	@see has_sub.
+     */
     template <>
     struct has_sub<XIndexBase>
     { static constexpr bool value = true; };
-    
+
+    /** Create XIndex pointer.
+	@param i Index to be wrapped.
+	@return Pointer to created index wrapper.
+     */
     template <class Index>
     inline XIndexPtr xindexPtr(const Sptr<Index>& i);
 
+    /** Specialization of xindexPtr().
+	If input index type is already a XIndex, the corresponding pointer is just passed.
+	This is to avoid unwanted chains of index wrappers.
+	@param i Input index.
+	@return i.
+     */
     template <>
     inline XIndexPtr xindexPtr<XIndexBase>(const Sptr<XIndexBase>& i);