Improve documentation in definitions.h

1 files changed, 31 insertions, 7 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 */