[doc] Docs on heap

Makefile

@@ -1,3 +1,4 @@
+.PHONY: doc
 ifeq ($(ARCH),)
 $(error Target architecture is not specified: $${ARCH})
 endif
@@ -25,5 +26,5 @@ clean:
 mkdirs:
 	@mkdir -p $(O) $(DIRS)
 
-_doc:
+doc:
 	@make -sC doc all

include/arch/amd64/mm/heap.h

@@ -24,4 +24,7 @@ void amd64_heap_init(heap_t *heap, uintptr_t phys_base, size_t sz);
  */
 size_t amd64_heap_blocks(const heap_t *heap);
 
+/**
+ * @brief Print kernel heap block list to debug output
+ */
 void amd64_heap_dump(const heap_t *heap);

include/sys/heap.h

@@ -3,7 +3,16 @@
 #pragma once
 #include <sys/types.h>
 
+/**
+ * @brief Common kernel heap alloc
+ * @see heap_alloc
+ */
 #define kmalloc(sz)     heap_alloc(heap_global, sz)
+
+/**
+ * @brief Common kernel heap free
+ * @see heal_free
+ */
 #define kfree(p)        heap_free(heap_global, p)
 
 /// Opaque type for kernel heap usage
@@ -14,12 +23,17 @@ extern heap_t *heap_global;
 
 /**
  * @brief Allocate `count' bytes
+ * @param heap Heap instance
  * @param count Number of bytes to allocate
+ * @return Virtual address of the block on success,
+ *         NULL otherwise
  */
 void *heap_alloc(heap_t *heap, size_t count);
 
 /**
- * @brief Make memory block at `ptr' usable again
+ * @brief Make memory block at `ptr' usable again if `ptr' is non-NULL
+ * @param heap Heap instance
+ * @param ptr Pointer to a heap block or NULL
  * @warning ptr must be a valid pointer allocated from the heap, otherwise
  *          kernel panic is raised
  */
@@ -27,6 +41,7 @@ void heap_free(heap_t *heap, void *ptr);
 
 /**
  * @brief Estimate heap free memory size
+ * @param heap Heap instance
  * @return Approximate number of usable bytes
  */
 size_t heap_info_free(heap_t *heap);