From 871910355d36032dce0e39c4f5a72fd84e967a0c Mon Sep 17 00:00:00 2001 From: Christian Zimmermann Date: Sat, 3 Feb 2024 16:44:34 +0100 Subject: [PATCH] cereal documentation --- src/include/memory/allocator.cc.h | 10 ++ src/include/memory/allocator.h | 7 +- src/include/operation/basic_operations.cc.h | 10 ++ src/include/operation/basic_operations.h | 10 ++ src/opt/cereal/include/cer_array.cc.h | 11 +- src/opt/cereal/include/cer_base.h | 18 ++- src/opt/cereal/include/cer_header.cc.h | 10 ++ src/opt/cereal/include/cer_header.h | 34 +++++- src/opt/cereal/include/cer_ranges.cc.h | 10 ++ src/opt/cereal/include/cer_type_register.cc.h | 10 ++ src/opt/cereal/include/cnorxz_cereal.h | 10 ++ src/opt/cereal/include/range_save_load.cc.h | 10 ++ src/opt/cereal/include/range_save_load.h | 20 +++- src/opt/cereal/include/utilities.cc.h | 10 ++ src/opt/cereal/include/utilities.h | 109 +++++++++++++++--- src/opt/hdf5/lib/h5_group.cc | 2 + src/tests/test_numbers.h | 2 + 17 files changed, 268 insertions(+), 25 deletions(-) diff --git a/src/include/memory/allocator.cc.h b/src/include/memory/allocator.cc.h index 352eb9c..2e50105 100644 --- a/src/include/memory/allocator.cc.h +++ b/src/include/memory/allocator.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file include/memory/allocator.cc.h + @brief Allocator template member function implementation + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + +**/ #ifndef __cxz_allocator_cc_h__ #define __cxz_allocator_cc_h__ diff --git a/src/include/memory/allocator.h b/src/include/memory/allocator.h index 92be7f3..bc90139 100644 --- a/src/include/memory/allocator.h +++ b/src/include/memory/allocator.h @@ -1,11 +1,10 @@ // -*- C++ -*- /** - @file include/memory/memcount.h - @brief ... + @file include/memory/allocator.h + @brief Allocator declaration - - Copyright (c) 2022 Christian Zimmermann. All rights reserved. + Copyright (c) 2024 Christian Zimmermann. All rights reserved. Mail: chizeta@f3l.de **/ diff --git a/src/include/operation/basic_operations.cc.h b/src/include/operation/basic_operations.cc.h index 9e8d3b5..df23e01 100644 --- a/src/include/operation/basic_operations.cc.h +++ b/src/include/operation/basic_operations.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file include/operation/basic_operations.cc.h + @brief Basic operations implementation + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_basic_operations_cc_h__ #define __cxz_basic_operations_cc_h__ diff --git a/src/include/operation/basic_operations.h b/src/include/operation/basic_operations.h index 150e183..8301fbe 100644 --- a/src/include/operation/basic_operations.h +++ b/src/include/operation/basic_operations.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file include/operation/basic_operations.h + @brief Basic operations declaration + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_basic_operations_h__ #define __cxz_basic_operations_h__ diff --git a/src/opt/cereal/include/cer_array.cc.h b/src/opt/cereal/include/cer_array.cc.h index 35f5c6d..076c658 100644 --- a/src/opt/cereal/include/cer_array.cc.h +++ b/src/opt/cereal/include/cer_array.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cer_array.cc.h + @brief Load and save implementation for MArray. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_array_cc_h__ #define __cxz_cereal_array_cc_h__ @@ -23,7 +33,6 @@ namespace CNORXZ { CXZ_ASSERT(version == 1u, "format version = " << version << " not supported"); cer::save_load(ar, "range", AB::mRange); - //ar(cereal::make_nvp("range", AB::mRange)); ar(cereal::make_nvp("data", mCont)); } } diff --git a/src/opt/cereal/include/cer_base.h b/src/opt/cereal/include/cer_base.h index 97710f9..127de76 100644 --- a/src/opt/cereal/include/cer_base.h +++ b/src/opt/cereal/include/cer_base.h @@ -1,19 +1,35 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cer_base.h + @brief CNORXZ Cereal basic types declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cer_base_h__ #define __cxz_cer_base_h__ -#define CXZ_CEREAL_FORMAT_VERION 1u +#define CXZ_CEREAL_FORMAT_VERION 1u /**< CNORXZ specific cereal format version. */ namespace CNORXZ { namespace cer { + /** **** + Archive format enum class. + */ enum class Format { BINARY = 1u, JSON = 2u, XML = 3u }; + /** **** + Content type enum class. + */ enum class ContentType { ARRAY = 1u, MAP = 2u diff --git a/src/opt/cereal/include/cer_header.cc.h b/src/opt/cereal/include/cer_header.cc.h index 64dcd2a..408cfd9 100644 --- a/src/opt/cereal/include/cer_header.cc.h +++ b/src/opt/cereal/include/cer_header.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cer_header.cc.h + @brief Load and save implementation for CNORXZ cereal data header. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_header_cc_h__ #define __cxz_cereal_header_cc_h__ diff --git a/src/opt/cereal/include/cer_header.h b/src/opt/cereal/include/cer_header.h index be677a1..946c2a8 100644 --- a/src/opt/cereal/include/cer_header.h +++ b/src/opt/cereal/include/cer_header.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cer_header.h + @brief CNORXZ Cereal data header declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_header_h__ #define __cxz_cereal_header_h__ @@ -9,13 +19,19 @@ namespace CNORXZ { namespace cer { + /** **** + Cereal data header struct. + */ struct Header { - String version; - String commit; - ContentType content; + String version; /**< CNORXZ version. */ + String commit; /**< CNORXZ git commit. */ + ContentType content; /**< Content type. */ }; + /** Create header. + @param content Content type. + */ inline Header mkHeader(const ContentType content) { Header o; @@ -24,10 +40,20 @@ namespace CNORXZ o.content = content; return o; } - + + /** Serialze header, store in archive. + @param ar Target archive. + @param h Input header. + @param version Version. + */ template void save(Archive& ar, const Header& h, const std::uint32_t version); + /** Deserialze header from archive. + @param ar Source archive. + @param h Target header reference. + @param version Version. + */ template void load(Archive& ar, Header& h, const std::uint32_t version); diff --git a/src/opt/cereal/include/cer_ranges.cc.h b/src/opt/cereal/include/cer_ranges.cc.h index ea2748e..7180e99 100644 --- a/src/opt/cereal/include/cer_ranges.cc.h +++ b/src/opt/cereal/include/cer_ranges.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cer_ranges.cc.h + @brief Load and save implementation for cnorxz ranges. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_ranges_cc_h__ #define __cxz_cereal_ranges_cc_h__ diff --git a/src/opt/cereal/include/cer_type_register.cc.h b/src/opt/cereal/include/cer_type_register.cc.h index 7e4ae5c..4c3ba4f 100644 --- a/src/opt/cereal/include/cer_type_register.cc.h +++ b/src/opt/cereal/include/cer_type_register.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cer_type_register.cc.h + @brief Register CNORXZ cereal types. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_type_register_cc_h__ #define __cxz_cereal_type_register_cc_h__ diff --git a/src/opt/cereal/include/cnorxz_cereal.h b/src/opt/cereal/include/cnorxz_cereal.h index 5d58780..d7410c2 100644 --- a/src/opt/cereal/include/cnorxz_cereal.h +++ b/src/opt/cereal/include/cnorxz_cereal.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/cnorxz_cereal.h + @brief CNORXZ Cereal main header + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #include "cer_base.h" #include "cer_header.h" diff --git a/src/opt/cereal/include/range_save_load.cc.h b/src/opt/cereal/include/range_save_load.cc.h index db6917c..e568257 100644 --- a/src/opt/cereal/include/range_save_load.cc.h +++ b/src/opt/cereal/include/range_save_load.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/range_save_load.cc.h + @brief CNORXZ Cereal range save load implementation. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __range_save_load_cc_h__ #define __range_save_load_cc_h__ diff --git a/src/opt/cereal/include/range_save_load.h b/src/opt/cereal/include/range_save_load.h index a60f0f6..5ef60bc 100644 --- a/src/opt/cereal/include/range_save_load.h +++ b/src/opt/cereal/include/range_save_load.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/range_save_load.h + @brief CNORXZ Cereal range save load declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __range_save_load_h__ #define __range_save_load_h__ @@ -8,8 +18,14 @@ namespace CNORXZ { namespace cer { - // use this function to register the range in the map of the range factories - // (otherwise there might be more than one instance of the same range) + /** Deserialize and register range from cereal archive. + Always use this function to load ranges from archives so that it is + registered in the map of the range factories. Otherwise there might be more + than one instance of the same range. + @param ar Archive to read from. + @param name Archive key. + @param r Target range pointer. + */ template RangePtr save_load(Archive& ar, const String& name, RangePtr& r); } diff --git a/src/opt/cereal/include/utilities.cc.h b/src/opt/cereal/include/utilities.cc.h index 790d3ae..678231d 100644 --- a/src/opt/cereal/include/utilities.cc.h +++ b/src/opt/cereal/include/utilities.cc.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/utilities.cc.h + @brief CNORXZ Cereal utilities implementation. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_utilities_cc_h__ #define __cxz_cereal_utilities_cc_h__ diff --git a/src/opt/cereal/include/utilities.h b/src/opt/cereal/include/utilities.h index e8e8750..6a7a0bf 100644 --- a/src/opt/cereal/include/utilities.h +++ b/src/opt/cereal/include/utilities.h @@ -1,3 +1,13 @@ +// -*- C++ -*- +/** + + @file opt/cereal/include/utilities.h + @brief CNORXZ Cereal utilities declaration. + + Copyright (c) 2024 Christian Zimmermann. All rights reserved. + Mail: chizeta@f3l.de + + **/ #ifndef __cxz_cereal_utilities_h__ #define __cxz_cereal_utilities_h__ @@ -14,68 +24,141 @@ namespace CNORXZ { namespace cer { - + /** **** + Output archive type trait. + @tparam F Format enum. + */ template struct OutputFormatMap {}; + /** Output archive for binary format. */ template <> struct OutputFormatMap - { typedef cereal::BinaryOutputArchive type; }; + { typedef cereal::BinaryOutputArchive type; /**< archive type. */ }; + /** Output archive for json format. */ template <> struct OutputFormatMap - { typedef cereal::JSONOutputArchive type; }; + { typedef cereal::JSONOutputArchive type; /**< archive type. */ }; + /** Output archive for xml format. */ template <> struct OutputFormatMap - { typedef cereal::XMLOutputArchive type; }; + { typedef cereal::XMLOutputArchive type; /**< archive type. */ }; + /** **** + Input archive type trait. + @tparam F Format enum. + */ template struct InputFormatMap {}; + /** Input archive for binary format. */ template <> struct InputFormatMap - { typedef cereal::BinaryInputArchive type; }; + { typedef cereal::BinaryInputArchive type; /**< archive type. */ }; + /** Input archive for json format. */ template <> struct InputFormatMap - { typedef cereal::JSONInputArchive type; }; + { typedef cereal::JSONInputArchive type; /**< archive type. */ }; + /** Input archive for xml format. */ template <> struct InputFormatMap - { typedef cereal::XMLInputArchive type; }; + { typedef cereal::XMLInputArchive type; /**< archive type. */ }; + /** Serialize MArray to stream + @tparam F Format enum class [BINARY,JSON,XML]. + @tparam T Array element value type. + @param os Output stream. + @param data Array to be serialized. + */ template void write(std::ostream& os, const MArray& data); + /** Deserialize MArray from stream + @tparam F Format enum class [BINARY,JSON,XML]. + @tparam T Array element value type. + @param is Input stream. + @param data Target array. + */ template void read(std::istream& is, MArray& data); + /** Serialize MArray and write to file. + @tparam F Format enum class [BINARY,JSON,XML]. + @tparam T Array element value type. + @param name File name. + @param data Array to be saved. + */ template void writeFile(const String& name, const MArray& data); + /** Read and deserialize MArray from cereal compatibel file. + @tparam F Format enum class [BINARY,JSON,XML]. + @tparam T Array element value type. + @param name File name. + @param data target array. + */ template void readFile(const String& name, MArray& data); + /** Serialize MArray and write to binary file. + @tparam T Array element value type. + @param name File name. + @param data Array to be saved. + */ template - void writeBINARYFile(const String& name, const MArray& data) { writeFile(name, data); } + inline void writeBINARYFile(const String& name, const MArray& data) + { writeFile(name, data); } + /** Read and deserialize MArray from cereal compatibel binary file. + @tparam T Array element value type. + @param name File name. + @param data target array. + */ template - void readBINARYFile(const String& name, MArray& data) { readFile(name, data); } + inline void readBINARYFile(const String& name, MArray& data) + { readFile(name, data); } + /** Serialize MArray and write to json file. + @tparam T Array element value type. + @param name File name. + @param data Array to be saved. + */ template - void writeJSONFile(const String& name, const MArray& data) { writeFile(name, data); } + inline void writeJSONFile(const String& name, const MArray& data) + { writeFile(name, data); } + /** Read and deserialize MArray from cereal compatibel json file. + @tparam T Array element value type. + @param name File name. + @param data target array. + */ template - void readJSONFile(const String& name, MArray& data) { readFile(name, data); } + inline void readJSONFile(const String& name, MArray& data) + { readFile(name, data); } + /** Serialize MArray and write to xml file. + @tparam T Array element value type. + @param name File name. + @param data Array to be saved. + */ template - void writeXMLFile(const String& name, const MArray& data) { writeFile(name, data); } + inline void writeXMLFile(const String& name, const MArray& data) + { writeFile(name, data); } + /** Read and deserialize MArray from cereal compatibel xml file. + @tparam T Array element value type. + @param name File name. + @param data target array. + */ template - void readXMLFile(const String& name, MArray& data) { readFile(name, data); } + inline void readXMLFile(const String& name, MArray& data) + { readFile(name, data); } } } diff --git a/src/opt/hdf5/lib/h5_group.cc b/src/opt/hdf5/lib/h5_group.cc index 7728b95..a5d093f 100644 --- a/src/opt/hdf5/lib/h5_group.cc +++ b/src/opt/hdf5/lib/h5_group.cc @@ -133,11 +133,13 @@ namespace CNORXZ return *this; } + /** @cond 0 */ struct InitContData { const ContentBase* parent; BIndex index; }; + /** @endcond */ static herr_t addName(hid_t id, const char* name, const H5L_info_t* info, void* x) { diff --git a/src/tests/test_numbers.h b/src/tests/test_numbers.h index 2a66357..0d4e52a 100644 --- a/src/tests/test_numbers.h +++ b/src/tests/test_numbers.h @@ -11,6 +11,7 @@ namespace CNORXZ { namespace Test { + /** @cond 0 */ class Numbers { private: @@ -51,6 +52,7 @@ namespace CNORXZ return Vector(b,e); } }; + /** @endcond */ } }