yrange/yindex: comments

src/include/ranges/crange.h

@@ -2,8 +2,7 @@
 /**
    
    @file include/ranges/crange.h
-   @brief ...
+   @brief CRange and CIndex declaration.
-
 
    Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
@@ -80,7 +79,7 @@ namespace CNORXZ
 	SizeT operator*() const;
 	
 	/** @copydoc IndexInterface::dim() */
-	SizeT dim() const; // = 1
+	SizeT dim() const;
 
 	/** @copydoc IndexInterface::range() */
 	Sptr<RangeType> range() const;
@@ -140,14 +139,14 @@ namespace CNORXZ
     public:
 	typedef CRange oType;
 
-	/** construct and setup factory
+	/** Construct and setup factory
-	    @param size size of the range to be constructed
+	    @param size Size of the range to be constructed
 	 */
 	CRangeFactory(SizeT size);
 
-	/** construct and setup factory
+	/** Construct and setup factory
-	    @param size size of the range to be constructed
+	    @param size Size of the range to be constructed
-	    @param ref range the range to be constructed is related to
+	    @param ref Range the range to be constructed is related to
 	 */
 	CRangeFactory(SizeT size, RangePtr ref);
 

src/include/ranges/yrange.h

@@ -2,8 +2,7 @@
 /**
    
    @file include/ranges/yrange.h
-   @brief ...
+   @brief YRange and YIndex declaration
-
 
    Copyright (c) 2022 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
@@ -24,6 +23,13 @@
 
 namespace CNORXZ
 {
+    /** ****
+	Specific index for YRanges.
+
+	A YIndex is a multi-index which consists of a set of sub-indices
+	and a format. In the case the index is used to access data, this format
+	determines the linearized memory position for a given sub-index combination.
+     */
     class YIndex : public IndexInterface<YIndex,Vector<DType>>
     {
     public:
@@ -32,59 +38,154 @@ namespace CNORXZ
 	typedef Vector<DType> MetaType;
 	
 	INDEX_RANDOM_ACCESS_ITERATOR_DEFS(MetaType);
+
+	/** Default constructor. */
 	YIndex() = default;
+
+	/** Move constructor. */
 	YIndex(YIndex&& i) = default;
+
+	/** Move assignment. */
 	YIndex& operator=(YIndex&& i) = default;
-	// no defaults:
+
+	/** Copy constructor.
+	    No default copy: Have to copy sub-index instances
+	 */
 	YIndex(const YIndex& i);
+
+	/** Copy assigment.
+	    No default copy: Have to copy sub-index instances
+	 */
 	YIndex& operator=(const YIndex& i);
 
+	/** Construct from sub-index pointers.
+	    @param is Vector of XIndex pointers.
+	 */
 	YIndex(const Vector<XIndexPtr>& is);
+
+	/** Construct from sub-index pointers, specify index format.
+	    @param bs Index format (YFormat).
+	    @param is Vector of XIndex pointers.
+	 */
 	YIndex(const YFormat& bs, const Vector<XIndexPtr>& is);
+
+	/** Construct from a range and an initial lexicographic position
+	    @param range Range to iterate over.
+	    @param lexpos Initial lexicographic position.
+	 */
 	YIndex(const RangePtr& range, SizeT lexpos = 0);
+
+	/** Construct from a range and an initial lexicographic position, specify format.
+	    @param range Range to iterate over.
+	    @param bs Index format.
+	    @param lexpos Initial lexicographic position.
+	 */
 	YIndex(const RangePtr& range, const YFormat& bs, SizeT lexpos = 0);
 
+	/** @copydoc IndexInterface::operator=(SizeT) */
 	YIndex& operator=(SizeT lexpos);
+
+	/** @copydoc IndexInterface::operator++() */
 	YIndex& operator++();
+
+	/** @copydoc IndexInterface::operator--() */
 	YIndex& operator--();
-	YIndex operator+(Int n) const; // equivalent to applying n times ++
+
+	/** @copydoc IndexInterface::operator+() */
+	YIndex operator+(Int n) const;
+
+	/** @copydoc IndexInterface::operator-() */
 	YIndex operator-(Int n) const;
+
+	/** @copydoc IndexInterface::operator-(CIndex) */
 	SizeT operator-(const YIndex& i) const;
+
+	/** @copydoc IndexInterface::operator+=() */
 	YIndex& operator+=(Int n);
+
+	/** @copydoc IndexInterface::operator-=() */
 	YIndex& 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*() */
 	Vector<DType> operator*() const;
 
+	/** @copydoc IndexInterface::dim() */
 	SizeT dim() const;
+
+	/** @copydoc IndexInterface::range() */
 	Sptr<YRange> range() const;
+
+	/** @copydoc IndexInterface::stepSize() */
 	UPos stepSize(const IndexId<0> id) const;
 
+	/** @copydoc IndexInterface::stringMeta() */
 	String stringMeta() const;
+
+	/** @copydoc IndexInterface::meta() */
 	Vector<DType> meta() const;
+
+	/** @copydoc IndexInterface::at() */
 	YIndex& at(const Vector<DType>& meta);
 
+	/** @copydoc IndexInterface::prange() */
+	RangePtr prange(const YIndex& last) const;
+
+	/** @copydoc IndexInterface::deepFormat() */
+	Vector<SizeT> deepFormat() const;
+
+	/** @copydoc IndexInterface::deepMax() */
+	Vector<SizeT> deepMax() const;
+
+	/** @copydoc IndexInterface::reformat() */
+	YIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
+
+	/** @copydoc IndexInterface::ifor() */
 	DXpr<None> ifor(const DXpr<None>& xpr, NoF&& f) const;
 
-	YIndex& operator()(const Sptr<YIndex>& i);
-	YIndex& operator()();
-
-	const DPack& pack() const;
-	RangePtr prange(const YIndex& last) const;
-	Vector<SizeT> deepFormat() const;
-	Vector<SizeT> deepMax() const;
-	const YFormat& format() const;
-	const YFormat& lexFormat() const;
-	YIndex& setFormat(const YFormat& bs);
-	YIndex& reformat(const Vector<SizeT>& f, const Vector<SizeT>& s);
-	
 	/** @copydoc IndexInterface::formatIsTrivial() */
 	bool formatIsTrivial() const;
 
+	/** Replace sub-index instances.
+	    All linearized positions are updated accordingly.
+	    @param i Pointer to YIndex which provides the new sub-index instance 
+	 */
+	YIndex& operator()(const Sptr<YIndex>& i);
+
+	/** Update all linearized positions. */
+	YIndex& operator()();
+
+	/** Get all sub-indices
+	    @return Pack of sub-indices
+	 */
+	const DPack& pack() const;
+
+	/** Get index format.
+	    @return The format.
+	 */
+	const YFormat& format() const;
+
+	/** Get lexicographic (trivial) index format.
+	    @return The lexicographic format.
+	 */
+	const YFormat& lexFormat() const;
+
+	/** Set the index format.
+	    @param bs The new format.
+	 */
+	YIndex& setFormat(const YFormat& bs);
+
     private:
 	inline Vector<SizeT> mkFormat() const;
 	inline Vector<SizeT> mkLexFormat() const;
@@ -107,26 +208,80 @@ namespace CNORXZ
 	UPos mLMax = 0;
     };
 
+    /** ****
+	Specialization: YIndex is a multi-index.
+	@see index_is_multi
+     */
     template <>
     struct index_is_multi<YIndex>
     { static constexpr bool value = true; };
 
+    /** ****
+	Specialization: YIndex has sub-indices.
+	@see has_sub
+     */
     template <>
     struct has_sub<YIndex>
     { static constexpr bool value = true; };
 
+    /** Create YIndex from an index pack assuming a trivial index format. 
+	@param pack Dynamic index pack.
+	@return The created YIndex.
+     */
     YIndex yindex(const DPack& pack);
+
+    /** Create YIndex from sub-indices assuming a trivial index format. 
+	@param is Vector of pointers to the sub-indices used in the YIndex.
+	@return The created YIndex.
+     */
     YIndex yindex(const Vector<XIndexPtr>& is);
+
+    /** Create YIndex from an index pack assuming a trivial index format. 
+	@param pack Dynamic index pack.
+	@return A shared pointer to the created YIndex.
+     */
     Sptr<YIndex> yindexPtr(const DPack& is);
+
+    /** Create YIndex from sub-indices assuming a trivial index format. 
+	@param is Vector of pointers to the sub-indices used in the YIndex.
+	@return A shared pointer to the created YIndex.
+     */
     Sptr<YIndex> yindexPtr(const Vector<XIndexPtr>& is);
+
+    /** Create YIndex from sub-indices. 
+	@param is Vector of pointers to the sub-indices used in the YIndex.
+	@param bs Index format.
+	@return A shared pointer to the created YIndex.
+     */
     Sptr<YIndex> yindexPtr(const Vector<SizeT>& bs, const Vector<XIndexPtr>& is);
 
+    /** ****
+	Specific factory for YRange.
+     */
     class YRangeFactory : public RangeFactoryBase
     {
     public:
+
+	/** Construct and setup factory.
+	    @param rvec Vector of ranges i.e. the sub-ranges the YRange consists of
+	 */
 	YRangeFactory(const Vector<RangePtr>& rvec);
+
+	/** Construct and setup factory.
+	    @param rvec Vector of ranges i.e. the sub-ranges the YRange consists of (move)
+	 */
 	YRangeFactory(Vector<RangePtr>&& rvec);
+
+	/** Construct and setup factory.
+	    @param rvec Vector of ranges i.e. the sub-ranges the YRange consists of
+	    @param ref Range the range to be constructed is related to
+	 */
 	YRangeFactory(const Vector<RangePtr>& rvec, const RangePtr& ref);
+
+	/** Construct and setup factory.
+	    @param rvec Vector of ranges i.e. the sub-ranges the YRange consists of (move)
+	    @param ref Range the range to be constructed is related to
+	 */
 	YRangeFactory(Vector<RangePtr>&& rvec, const RangePtr& ref);
 
     private:
@@ -138,6 +293,13 @@ namespace CNORXZ
 
     };
 
+    /** ****
+	Dynamic multi-dimensional range
+
+	Dimension and sub-range types are determined at runtime
+	The size of the range is given by the product of the
+	sizes of all sub-ranges.
+     */
     class YRange : public RangeInterface<YRange>
     {
     public:
@@ -169,8 +331,16 @@ namespace CNORXZ
 	SERIALIZATION_FUNCTIONS_NOPUB;
     };
 
+    /** Create YRange from sub-ranges.
+	@param rs Vector of pointers to the sub-ranges used by the YRange.
+	@return A shared pointer to the created YRange.
+     */
     RangePtr yrange(const Vector<RangePtr>& rs);
-    
+
+    /** ****
+	Specialize RangeCast for casts to YRange.
+	@see RangeCast
+     */
     template <>
     struct RangeCast<YRange>
     {