From fcf0358b0597b733f36b0c862bf18a98efdea224 Mon Sep 17 00:00:00 2001
From: bd <bdunahu@operationnull.com>
Date: Sun, 9 Mar 2025 16:25:20 -0400
Subject: Improve documentation in definitions.h

---
 inc/definitions.h  | 38 +++++++++++++++++++++++++++++++-------
 src/utils/utils.cc |  6 +++---
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/inc/definitions.h b/inc/definitions.h
index 4b01be9..877065e 100644
--- a/inc/definitions.h
+++ b/inc/definitions.h
@@ -2,25 +2,49 @@
 #define DEFINITIONS_H
 #include <cmath>
 
-/* The number of bits to specify a word in a line
+/**
+ * The number of bits to specify a word in a line
  */
 #define LINE_SPEC 2
+/**
+ * The total number of words in a line
+ */
 #define LINE_SIZE (int)pow(2, 2)
 
-/* The number of bits to specify a memory line
- * (/ (expt 2 15) 4)
+/**
+ * The number of bits to specify a memory line
+ * calculated as: (/ (expt 2 15) 4)
  */
 #define MEM_SPEC 13
+/**
+ * The total number of words in memory
+ */
 #define MEM_SIZE (int)pow(2, MEM_SPEC)
 
-/* The number of bits to specify a l1 cache line
+/**
+ * The number of bits to specify a l1 cache line
  */
 #define L1_CACHE_SPEC 5
+/**
+ * The total number of words in l1 cache
+ */
 #define L1_CACHE_SIZE (int)pow(2, L1_CACHE_SPEC)
 
-/* Parses some bits.
+/**
+ * Return the N least-significant bits from integer K using a bit mask
+ * @param the integer to be parsed
+ * @param the number of bits to be parsed
+ * @return the N least-significant bits from K
+ */
+#define GET_LS_BITS(k, n) ((k) & ((1 << (n)) - 1))
+/**
+ * Return the bits from integer K starting at N and ending at M using a bit
+ * mask
+ * @param the integer to be parsed
+ * @param the index of the starting bit to be parsed
+ * @param the index of the ending bit to be parsed
+ * @return a section of bits from K
  */
-#define LAST(k, n) ((k) & ((1 << (n)) - 1))
-#define MID(k, m, n) LAST((k) >> (m), ((n) - (m)))
+#define GET_MID_BITS(k, m, n) GET_LS_BITS((k) >> (m), ((n) - (m)))
 
 #endif /* DEFINITIONS_H_INCLUDED */
diff --git a/src/utils/utils.cc b/src/utils/utils.cc
index 52be177..dfeb2b3 100644
--- a/src/utils/utils.cc
+++ b/src/utils/utils.cc
@@ -4,8 +4,8 @@
 void get_bit_fields(int address, int *tag, int *index, int *offset)
 {
 	*tag =
-		MID(address, LINE_SPEC + L1_CACHE_SPEC,
+		GET_MID_BITS(address, LINE_SPEC + L1_CACHE_SPEC,
 			MEM_SPEC + LINE_SPEC + L1_CACHE_SPEC);
-	*index = MID(address, LINE_SPEC, L1_CACHE_SPEC + LINE_SPEC);
-	*offset = LAST(address, LINE_SPEC);
+	*index = GET_MID_BITS(address, LINE_SPEC, L1_CACHE_SPEC + LINE_SPEC);
+	*offset = GET_LS_BITS(address, LINE_SPEC);
 }
-- 
cgit v1.2.3