From b60355c48afd44caff44ee1ba3c93126416e2107 Mon Sep 17 00:00:00 2001
From: Stefan Bucur <stefanb@zytor.com>
Date: Sat, 16 Aug 2008 18:07:27 +0300
Subject: Added source comments to some internal routines.

---
 com32/include/sys/module.h      | 14 ++++++++++++--
 com32/lib/sys/module/elfutils.h | 37 ++++++++++++++++++++++++++++++++++---
 2 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/com32/include/sys/module.h b/com32/include/sys/module.h
index c3c077ad..e09f1bf8 100644
--- a/com32/include/sys/module.h
+++ b/com32/include/sys/module.h
@@ -42,6 +42,12 @@ typedef int (*module_init_t)(void);
  */
 typedef void (*module_exit_t)(void);
 
+/**
+ * module_main_t - pointer to an entry routine
+ *
+ * The entry routine is present only in executable modules, and represent
+ * the entry point for the program.
+ */
 typedef int (*module_main_t)(int, char**);
 
 
@@ -166,7 +172,7 @@ extern struct list_head modules_head;
 
 
 /**
- * for_each_module -
+ * for_each_module - iterator loop through the list of loaded modules.
  */
 #define for_each_module(m)	list_for_each_entry(m, &modules_head, list)
 
@@ -239,7 +245,11 @@ extern int module_load_shallow(struct elf_module *module);
 extern int module_unload(struct elf_module *module);
 
 /**
- * module_unloadable -
+ * module_unloadable - checks whether the given module can be unloaded.
+ * @module: the module descriptor structure
+ *
+ * A module can be unloaded from the system when no other modules depend on it,
+ * that is, no symbols are referenced from it.
  */
 extern int module_unloadable(struct elf_module *module);
 
diff --git a/com32/lib/sys/module/elfutils.h b/com32/lib/sys/module/elfutils.h
index b8df660e..b18968f3 100644
--- a/com32/lib/sys/module/elfutils.h
+++ b/com32/lib/sys/module/elfutils.h
@@ -4,19 +4,30 @@
 #include <elf.h>
 #include <stdlib.h>
 
-// Returns a pointer to the ELF header structure
+/**
+ * elf_get_header - Returns a pointer to the ELF header structure.
+ * @elf_image: pointer to the ELF file image in memory
+ */
 static inline Elf32_Ehdr *elf_get_header(void *elf_image) {
 	return (Elf32_Ehdr*)elf_image;
 }
 
-// Returns a pointer to the first entry in the Program Header Table
+/**
+ * elf_get_pht - Returns a pointer to the first entry in the PHT.
+ * @elf_image: pointer to the ELF file image in memory
+ */
 static inline Elf32_Phdr *elf_get_pht(void *elf_image) {
 	Elf32_Ehdr *elf_hdr = elf_get_header(elf_image);
 
 	return (Elf32_Phdr*)((Elf32_Off)elf_hdr + elf_hdr->e_phoff);
 }
 
-// Returns the element with the given index in the PTH
+//
+/**
+ * elf_get_ph - Returns the element with the given index in the PTH
+ * @elf_image: pointer to the ELF file image in memory
+ * @index: the index of the PHT entry to look for
+ */
 static inline Elf32_Phdr *elf_get_ph(void *elf_image, int index) {
 	Elf32_Phdr *elf_pht = elf_get_pht(elf_image);
 	Elf32_Ehdr *elf_hdr = elf_get_header(elf_image);
@@ -24,10 +35,30 @@ static inline Elf32_Phdr *elf_get_ph(void *elf_image, int index) {
 	return (Elf32_Phdr*)((Elf32_Off)elf_pht + index * elf_hdr->e_phentsize);
 }
 
+/**
+ * elf_hash - Returns the index in a SysV hash table for the symbol name.
+ * @name: the name of the symbol to look for
+ */
 extern unsigned long elf_hash(const unsigned char *name);
+
+/**
+ * elf_gnu_hash - Returns the index in a GNU hash table for the symbol name.
+ * @name: the name of the symbol to look for
+ */
 extern unsigned long elf_gnu_hash(const unsigned char *name);
 
+/**
+ * elf_malloc - Allocates memory to be used by ELF module contents.
+ * @memptr: pointer to a variable to hold the address of the allocated block.
+ * @alignment: alignment constraints of the block
+ * @size: the required size of the block
+ */
 extern int elf_malloc(void **memptr, size_t alignment, size_t size);
+
+/**
+ * elf_free - Releases memory previously allocated by elf_malloc.
+ * @memptr: the address of the allocated block
+ */
 extern void elf_free(void *memptr);
 
 #endif /*ELF_UTILS_H_*/
-- 
cgit