Add descriptions and comments for block_header files.

block_header.c

@@ -1,5 +1,10 @@
 #include "block_header.h"
 
+/**
+ * \brief Get the address of the block header of a memory block.
+ *
+ * \param ptr The data part of the memory block.
+ */
 block_header_t * get_header(void *ptr);
 
 block_header_t * get_header(void *ptr) {
@@ -42,6 +47,7 @@ void remove_block(void *block, void *starting_node) {
 
     void *current_node, *previous_node;
 
+    // Traverse a list starting from the starting node until block is found.
     for(current_node = starting_node; current_node != NULL; 
             current_node = get_next(current_node)) {
         if(current_node == block) {

block_header.h

@@ -1,38 +1,102 @@
+/**
+ * \file 	block_header.h
+ * \author 	Ioannis Koutras (joko@microlab.ntua.gr)
+ * \date 	September, 2011
+ * \brief 	Block header structure and functions, and memory block functions.
+ */
+
 #ifndef BLOCK_HEADER_H
 #define BLOCK_HEADER_H
 
 #include <stddef.h>
 #include <stdbool.h>
 
+/**
+ * \brief The header structure of every memory block inside a heap.
+ */
 typedef struct block_header_s {
-	size_t size;
-	size_t requested_size;
-	size_t previous_size;
-	void *next;
+	size_t size; /**< \brief The size of the data part. */
+	size_t requested_size; /**< \brief The requested size of the data part */
+	size_t previous_size; /**< \brief The size of the data part of the
+				previous block in the memory space */
+	void *next; /**< \brief The next memory block in the list that the
+		      current block belongs to */
 } block_header_t;
 
+/**
+ * \brief The size of the header in number of bytes
+ */
 #define HEADER_SIZE sizeof(block_header_t)
 
+/**
+ * \brief Get the next memory block.
+ *
+ * \param ptr The pointer to the data part of the current memory block.
+ *
+ * \return The pointer of the data part of the next (in list) memory block.
+ * \retval NULL There is no next memory block in the list.
+ */
 void * get_next(void *ptr);
 
+/**
+ * \brief Get the size of the memory block's data
+ *
+ * \param ptr The pointer to the data part of the current memory block.
+ *
+ * \return The size of the data part of the current memory block.
+ */
 size_t get_size(void *ptr);
 
+/**
+ * \brief Set the size of the memory block's data
+ *
+ * \param ptr 	The pointer to the data part of the current memory block.
+ * \param size 	The size of the data part of the current memory block.
+ */
 void set_size(void *ptr, size_t size);
+
+/**
+ * \brief Set the requested size of memory block's data
+ *
+ * \param ptr 	The pointer to the data part of the current memory block.
+ * \param size 	The requested size for the data part of the current memory
+ * block.
+ */
 void set_requested_size(void *ptr, size_t size);
 
+/**
+ * \brief Set the next memory block of a block
+ *
+ * \param block 	The pointer to the data part of the current memory
+ * block.
+ * \param next_block 	The pointer to the data part of the next memory block.
+ */
 void set_next(void *block, void *next_block);
 
+/**
+ * \brief Check if previous block (in the memory space) belongs to a free list
+ */
 bool is_previous_free(void *ptr);
 
+/**
+ * \brief Get the size of the previous block (in the memory space) 
+ *
+ * \param ptr 	The pointer to the data part of the current memory block.
+ */
 size_t get_previous_size(void *ptr);
 
+/**
+ * \brief Get the previous memory block (in the memory space)
+ *
+ * \param ptr 	The pointer to the data part of the current memory block.
+ */
 void * get_previous(void *ptr);
 
 /**
- * Removes a memory block from a singly linked list of memory blocks.
+ * \brief Removes a memory block from a singly linked list of memory blocks.
  *
- * @param *block The block to be removed.
- * @param *starting_node The starting memory block of the list.
+ * \param *block The block to be removed.
+ * \param *starting_node The starting memory block of the list.
  */
 void remove_block(void *block, void *starting_node);