WIP: hdf5 documentation

src/include/ranges/ranges.h

@@ -2,10 +2,9 @@
 /**
    
    @file include/ranges/ranges.h
-   @brief ...
+   @brief Ranges main header
 
-
-   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
    Mail: chizeta@f3l.de
    
 **/

src/opt/hdf5/include/cnorxz_hdf5.cc.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/cnorxz_hdf5.cc.h
+   @brief CNORXZ HDF5 template sources header
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #include "h5_content_base.cc.h"
 #include "h5_type_id.cc.h"

src/opt/hdf5/include/cnorxz_hdf5.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/cnorxz_hdf5.h
+   @brief CNORXZ HDF5 main header
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #include "h5_content_base.h"
 #include "h5_file.h"

src/opt/hdf5/include/h5_content_base.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_content_base.h
+   @brief Abstract content base class declaration
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_content_base_h__
 #define __cxz_h5_content_base_h__
@@ -12,49 +22,122 @@ namespace CNORXZ
     {
 	// TODO: IO save error handling !!!
 
+	/** *****
+	    Enum indicating the content type.
+	    Used by ContainerBase derivates to indicate the derived type.
+	 */
 	enum class ContentType {
-	    ATTR = 1,
-	    FILE = 2,
-	    GROUP = 3,
-	    DSET = 4,
-	    TABLE = 5,
-	    VALUE = 6,
+	    NONE = 0,
+	    FILE = 1,
+	    GROUP = 2,
+	    DSET = 3,
+	    TABLE = 4,
 	};
 
+	/** ****
+	    Abstract base class for handling hdf5 objects.
+	 */
 	class ContentBase
 	{
 	public:
-	    DEFAULT_MEMBERS(ContentBase);
+	    DEFAULT_MEMBERS(ContentBase); /**< Default constructors and assignments. */
+
+	    /** Construct the class.
+		@param _name Content name.
+		@param _parent Parent content object. Leave null for the root object.
+	     */
 	    ContentBase(const String& _name, const ContentBase* _parent = nullptr);
+
+	    /** Virtual default destructor. */
 	    virtual ~ContentBase() = default;
 
+	    /** Get the content type.
+		@return Content type.
+	     */
 	    virtual ContentType type() const = 0;
+
+	    /** Check if in read-only mode
+		@return True if read-only else false.
+	     */
 	    virtual bool ro() const = 0;
+
+	    /** Open object.
+		@return Reference to this object.
+	     */
 	    virtual ContentBase& open() = 0;
+
+	    /** Close object.
+		@return Reference to this object.
+	     */
 	    virtual ContentBase& close() = 0;
+
+	    /** Get object path.
+		@return Absolute hdf5 file internal path of this object.
+	     */
 	    virtual String path() const = 0;
+
+	    /** Get the file name.
+		@return Name of the hdf5 file this object is stored in.
+	     */
 	    virtual String filename() const = 0;
 
+	    /** Get object name.
+		@return The name of this object.
+	     */
 	    const String& name() const;
-	    const ContentBase* parent() const;
-	    RangePtr range() const;
-	    hid_t id() const;
-	    inline bool isOpen() const { return mId != 0; }
 
+	    /** Get parent object.
+		@return Pointer to the parent of this object.
+	     */
+	    const ContentBase* parent() const;
+
+	    /** Get object id.
+		@return hdf5 id of the h5 object maintained by this object.
+	     */
+	    hid_t id() const;
+
+	    /** Check if object is open, i.e. if there is a valid hdf5 id.
+		@return True if object is open else false.
+	     */
+	    bool isOpen() const;
+
+	    /** Add attribute to this object.
+		@tparam T Attribute value type.
+		@param name Attribute name.
+		@param value Attribute value.
+	     */
 	    template <typename T>
 	    ContentBase& addAttribute(const String& name, const T& value);
+
+	    /** Get an attribute of this object.
+		@param name Attribute name.
+		@return The attribute value as DType.
+	     */
 	    DType getAttribute(const String& name) const;
+
+	    /** Check if attribute of given name exists in this object.
+		@param name Attribute name.
+		@return True if attribute exists else false.
+	     */
 	    bool attributeExists(const String& name) const;
+
+	    /** Get all attributes of this object.
+		@return Std map of key-value pairs.  
+	     */
 	    std::map<String,DType> getAttributes() const;
+
+	    /** Get all attributes of this object and all its parent objects, recursively.
+		@return Std map of key-value pairs.  
+	     */
 	    std::map<String,DType> getRecursiveAttributes() const; // + all parent's attributes
 	    
 	protected:
-	    String mName;
-	    const ContentBase* mParent = nullptr;
-	    RangePtr mRange;
-	    hid_t mId = 0;
+	    String mName; /**< Name of this object. */
+	    const ContentBase* mParent = nullptr; /**< Pointer to this object's parent. */
+	    hid_t mId = 0; /**< hdf5 identifier of the hdf5 object handled by this object. */
 	};
 
+	/** Shortcut for a shared pointer to an abstract content object. */
 	typedef Sptr<ContentBase> ContentPtr;
 
     }

src/opt/hdf5/include/h5_file.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_file.h
+   @brief Group declaration.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_file_h__
 #define __cxz_h5_file_h__
@@ -10,14 +20,25 @@ namespace CNORXZ
 {
     namespace hdf5
     {
-	// maybe introduce abstraction layer between as base for File and Group
+	/** ****
+	    Class to handle hdf5 file objects.
+	    Objects of this type usually serve as root object
+	    so they don't have any parent.
+	 */
 	class File : public Group
 	{
 	public:
 	    typedef URange<String> RangeT;
 	    
-	    DEFAULT_MEMBERS(File);
+	    DEFAULT_MEMBERS(File); /**< Default constructors and assignments. */
+
+	    /** Construct the class.
+		@param _name Path to the hdf5 file to be handled.
+		@param _ro Open in read-only mode if true, otherwise have write access.
+	     */
 	    File(const String& fname, bool _ro = true);
+
+	    /** Destructor. Release all involved hdf5 ids. */
 	    ~File();
 
 	    virtual ContentType type() const override final;

src/opt/hdf5/include/h5_group.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_group.h
+   @brief Group declaration.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_group_h__
 #define __cxz_h5_group_h__
@@ -9,11 +19,21 @@ namespace CNORXZ
 {
     namespace hdf5
     {
+	/** ****
+	    Class to handle hdf5 groups.
+	 */
 	class Group : public ContentBase
 	{
 	public:
-	    DEFAULT_MEMBERS(Group);
+	    DEFAULT_MEMBERS(Group); /**< Default constructors and assignments. */
+
+	    /** Construct the class.
+		@param _name Group name.
+		@param _parent Parent content object.
+	     */
 	    Group(const String& gname, const ContentBase* _parent);
+
+	    /** Destructor. Release all involved hdf5 ids. */
 	    ~Group();
 
 	    virtual ContentType type() const override;
@@ -23,43 +43,114 @@ namespace CNORXZ
 	    virtual String path() const override;
 	    virtual String filename() const override;
 
-	    virtual Int exists() const;
+	    /** Check if group exists in the parent object.
+		@return 1 if group exists, 0 if not, -1 if an error occured.
+	     */
+	    virtual Int exists() const; // TODO: virtual function of base class
 
+	    /** Get object contained by this group.
+		@param name Object name.
+		@return Pointer to the object.
+	     */
 	    const ContentPtr& get(const String& name) const;
+
+	    /** Get object contained by this group as group.
+		Checks if the object is a group.
+		@param name Group name.
+		@return Pointer to the group.
+	     */
 	    Sptr<Group> getGroup(const String& name) const;
+
+	    /** Get object contained by this group as table.
+		Checks if the object is a table.
+		@param name Table name.
+		@return Pointer to the table.
+	     */
 	    Sptr<Table> getTable(const String& name) const;
+
+	    /** Get object contained by this group as dataset.
+		Checks if the object is a table.
+		@param name Dataset name.
+		@return Pointer to the dataset.
+	     */
 	    Sptr<Dataset> getDataset(const String& name) const;
 
+	    /** Get object contained by this group as table for given value type.
+		Checks if the object is a table.
+		@tparam Ts Table entry types.
+		@param name Table name.
+		@param proto Empty prototype (template argument resolution).
+		@return Pointer to the table.
+	     */
 	    template <typename... Ts>
 	    Sptr<STable<Ts...>> getTable(const String& name, Tuple<Ts...> proto);
 
+	    /** Get object contained by this group as dataset for given value type.
+		Checks if the object is a dataset.
+		@tparam T Dataset value type.
+		@param name Dataset name.
+		@param proto Empty prototype (template argument resolution).
+		@return Pointer to the dataset.
+	     */
 	    template <typename T>
 	    Sptr<SDataset<T>> getDataset(const String& name, T proto);
 
+	    /** Get objects contained by this group.
+		@returns MArray of object pointers.
+	     */
 	    const MArray<ContentPtr>& get() const;
+
+	    /** Add a new group to this group.
+		@param name Name of the created group.
+	     */
 	    Group& addGroup(const String& name);
 
+	    /** Add a new table to this group.
+		@tparam Ts Table element types.
+		@param name Name of the created table.
+		@param data Table data.
+		@param fnames Table field names.
+	     */
 	    template <typename... Ts>
 	    Group& addTable(const String& name, const ArrayBase<Tuple<Ts...>>& data,
 			    const Arr<String,sizeof...(Ts)>& fnames);
 
+	    /** Add a new dataset to this group.
+		@tparam T Value type.
+		@param name Name of the created dataset.
+		@param data Dataset data.
+	     */
 	    template <typename T>
 	    Group& addDataset(const String& name, const ArrayBase<T>& data);
 
+	    /** Iterate over all group elements (const).
+		@param F function object to be executed on each group element.
+	     */
 	    template <class F>
 	    decltype(auto) iter(F&& f) const;
 
+	    /** Iterate recursively over all group elements (const).
+		@param F function object to be executed on each group element.
+	     */
 	    template <class F>
 	    decltype(auto) iterRecursive(F&& f) const;
 
+	    /** Iterate over all group elements.
+		@param F function object to be executed on each group element.
+	     */
 	    template <class F>
 	    decltype(auto) iter(F&& f);
 
+	    /** Iterate recursively over all group elements.
+		@param F function object to be executed on each group element.
+	     */
 	    template <class F>
 	    decltype(auto) iterRecursive(F&& f);
 
 	protected:
 
+	    MArray<ContentPtr> mCont; /**< Group elements. */
+
 	    template <typename C, class F>
 	    static void recursion(const C& c, F&& f)
 	    {
@@ -72,8 +163,6 @@ namespace CNORXZ
 		}
 	    }
 	    
-	    MArray<ContentPtr> mCont;
-
 	    void mkCont();
 	    AIndex<ContentPtr> getIndexTo(const String& name) const;
 	    BIndex<ContentPtr> getIndexTo(const String& name);

src/opt/hdf5/include/h5_table.h

@@ -1,3 +1,13 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/include/h5_table.h
+   @brief Table declaration.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #ifndef __cxz_h5_table_h__
 #define __cxz_h5_table_h__
@@ -9,13 +19,23 @@ namespace CNORXZ
 {
     namespace hdf5
     {
+	/** ****
+	    Class to handle hdf5 tables.
+	 */
 	class Table : public ContentBase
 	{
 	public:
 	    typedef std::pair<SizeT,String> FieldID;
 	    
-	    DEFAULT_MEMBERS(Table);
+	    DEFAULT_MEMBERS(Table); /**< Default constructors and assignments. */
+
+	    /** Construct the class.
+		@param _name Table name.
+		@param _parent Parent content object.
+	     */
 	    Table(const String& name, const ContentBase* _parent);
+
+	    /** Destructor. Release all involved hdf5 ids. */
 	    ~Table();
 
 	    virtual ContentType type() const override final;
@@ -25,17 +45,57 @@ namespace CNORXZ
 	    virtual String path() const override final;
 	    virtual String filename() const override final;
 
+	    /** Ininitialize table field names.
+		@param fnames Table field names.
+	     */
 	    Table& initFieldNames(const Vector<String>& fnames);
+
+	    /** Initialize the table.
+		@param n Number of records (rows).
+		@param data Table data.
+		@param dsize Record type size.
+		@param chunk_size Chunk size.
+	     */
 	    Table& initTable(SizeT n, const void* data, SizeT dsize, SizeT chunk_size);
+
+	    /** Append records to the table.
+		@param n Number of records to append.
+		@param data Records data.
+	     */
 	    Table& appendRecords(SizeT n, const void* data);
+
+	    /** Read records.
+		@param pos Number of first record to read.
+		@param n Number of records to read.
+		@param data Target pointer.
+	     */
 	    Table& readRecords(SizeT pos, SizeT n, char* data);
+
+	    /** Read record.
+		@param pos Number of the record to be read.
+		@return DType array with containing the record data.
+	     */
 	    MArray<DType> readRecord(SizeT pos) const;
+
+	    /** Read table.
+		@return DType array containing the table data.
+	     */
 	    MArray<DType> read() const;
 
+	    /** Iterate over table records.
+		@param F function object to be executed on each table record.
+	     */
 	    template <class F>
 	    decltype(auto) iterRecords(F&& f) const;
 
+	    /** Get fields range.
+		@return Pointer to the range.
+	     */
 	    const RangePtr& fields() const;
+
+	    /** Get records range.
+		@return Pointer to the range.
+	     */
 	    const RangePtr& records() const;
 
 	protected:

src/opt/hdf5/lib/h5_content_base.cc

@@ -1,3 +1,15 @@
+// -*- C++ -*-
+/**
+
+   @file opt/hdf5/lib/h5_content_base.cc
+   @brief Content base member function implementation.
+
+   Implementation of all non-virtual member functions of ContentBase.
+
+   Copyright (c) 2024 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+
+ **/
 
 #include "h5_content_base.h"
 
@@ -19,16 +31,16 @@ namespace CNORXZ
 	    return mParent;
 	}
 
-	RangePtr ContentBase::range() const
-	{
-	    return mRange;
-	}
-
 	hid_t ContentBase::id() const
 	{
 	    return mId;
 	}
 
+	bool isOpen() const
+	{
+	    return mId != 0;
+	}
+
 	DType ContentBase::getAttribute(const String& name) const
 	{
 	    CXZ_ASSERT(attributeExists(name), "no attribute with name '" << name