From a7c1aad6fc73152d6867c66287ce1b98d83f02e1 Mon Sep 17 00:00:00 2001
From: Christian Zimmermann <christian.zimmermann@ur.de>
Date: Sun, 10 Dec 2023 18:59:09 +0100
Subject: [PATCH] comment memory section

---
 src/include/memory/allocator.h | 41 ++++++++++++++++++++++++++++++----
 src/include/memory/memcount.h  | 34 +++++++++++++++++++++++++---
 src/include/memory/memory.cc.h | 11 +++++++++
 src/include/memory/memory.h    | 11 +++++++++
 src/lib/memory/memcount.cc     | 11 +++++++++
 5 files changed, 101 insertions(+), 7 deletions(-)

diff --git a/src/include/memory/allocator.h b/src/include/memory/allocator.h
index 552f2dc..92be7f3 100644
--- a/src/include/memory/allocator.h
+++ b/src/include/memory/allocator.h
@@ -1,3 +1,14 @@
+// -*- C++ -*-
+/**
+   
+   @file include/memory/memcount.h
+   @brief ...
+
+
+   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+   
+**/
 
 #ifndef __cxz_allocator__
 #define __cxz_allocator__
@@ -16,7 +27,10 @@
 
 namespace CNORXZ
 {
-
+    /** *****
+	Allocator implementation
+	Takes care of proper alignment
+     */
     template <typename T>
     class Allocator
     {
@@ -24,26 +38,45 @@ namespace CNORXZ
 
 	typedef T value_type;
 	
-	static constexpr SizeT type_size = sizeof(T);	
-	static constexpr SizeT N = MAX_VSIZE;
+	static constexpr SizeT type_size = sizeof(T); /** < type size */
+	static constexpr SizeT N = MAX_VSIZE; /** < size of the larges available intrinsics vector */
 
+	/** ***
+	    Aligned data block type
+	    The size equals the maximal intrinsics vectors size
+	 */
         struct VX
         {
             alignas(N) char x[N];
         };
-        
+
+	/** default constructor */
 	Allocator() = default;
 
+	/** (copy) construct from allocator for different data type
+	    @tparam U input data type
+	    @param x input allocator
+	 */
 	template <typename U>
 	Allocator(const Allocator<U>& x) {}
 
+	/** allocate n element of type T
+	    @param n number of elements
+	 */
 	T* allocate(SizeT n);
+
+	/** deallocate n elements
+	    @param p pointer to first element
+	    @param n number of elements
+	 */
 	void deallocate(T* p, SizeT n);
     };
 
+    /** compare two cnorxz allocators; equality check returns always true */
     template <class T, class U>
     bool operator==(const Allocator<T>& a, const Allocator<U>& b);
 
+    /** compare two cnorxz allocators; unequality check returns always false */
     template <class T, class U>
     bool operator!=(const Allocator<T>& a, const Allocator<U>& b);
 
diff --git a/src/include/memory/memcount.h b/src/include/memory/memcount.h
index 8a71768..f69c261 100644
--- a/src/include/memory/memcount.h
+++ b/src/include/memory/memcount.h
@@ -1,3 +1,14 @@
+// -*- C++ -*-
+/**
+   
+   @file include/memory/memcount.h
+   @brief ...
+
+
+   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+   
+**/
 
 #ifndef __cxz_memcount_h__
 #define __cxz_memcount_h__
@@ -6,16 +17,33 @@
 
 namespace CNORXZ
 {
+    /** *****
+	Static class to track memory usage by cnorxz types
+	The usage variable can be changed only be an Allocator instance
+
+	@see Allocator
+     **/
     class MemCount
     {
     private:
-	static SizeT sMemUsage;
+	static SizeT sMemUsage; /**< current memory usage (bytes) */ 
+
+	/** increas memory usage
+	    @param x number of bytes
+	 */
 	static void add(SizeT x);// { sMemUsage += x; }
+	
+	/** decreas memory usage
+	    @param x number of bytes
+	 */
 	static void sub(SizeT x);// { sMemUsage -= x; }
 	
     public:
-	MemCount() = delete; // static only
-	static SizeT usage();// { return sMemUsage; }
+	/** no instance construction (static) */
+	MemCount() = delete;
+
+	/** return current memory usage (bytes) */
+	static SizeT usage();
 
 	template <typename T>
 	friend class Allocator;
diff --git a/src/include/memory/memory.cc.h b/src/include/memory/memory.cc.h
index cf7861a..19a1181 100644
--- a/src/include/memory/memory.cc.h
+++ b/src/include/memory/memory.cc.h
@@ -1,2 +1,13 @@
+// -*- C++ -*-
+/**
+   
+   @file include/memory/memory.cc.h
+   @brief ...
+
+
+   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+   
+**/
 
 #include "allocator.cc.h"
diff --git a/src/include/memory/memory.h b/src/include/memory/memory.h
index 5550f77..6f1ec8c 100644
--- a/src/include/memory/memory.h
+++ b/src/include/memory/memory.h
@@ -1,3 +1,14 @@
+// -*- C++ -*-
+/**
+   
+   @file include/memory/memory.h
+   @brief ...
+
+
+   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+   
+**/
 
 #include "allocator.h"
 #include "memcount.h"
diff --git a/src/lib/memory/memcount.cc b/src/lib/memory/memcount.cc
index 76a4ba2..7ca0ebb 100644
--- a/src/lib/memory/memcount.cc
+++ b/src/lib/memory/memcount.cc
@@ -1,3 +1,14 @@
+// -*- C++ -*-
+/**
+   
+   @file lib/memory/memcount.cc
+   @brief ...
+
+
+   Copyright (c) 2022 Christian Zimmermann. All rights reserved.
+   Mail: chizeta@f3l.de
+   
+**/
 
 #include "memory/memcount.h"