From 05e8b329edc7c55eec967c3caba1982c173025e3 Mon Sep 17 00:00:00 2001
From: John Hodge <tpg@mutabah.net>
Date: Tue, 7 Sep 2010 09:34:25 +0800
Subject: [PATCH] Fixing up doxygen comments

---
 Kernel/arch/x86/include/vm8086.h    |  2 +-
 Kernel/arch/x86/time.c              |  2 +-
 Kernel/arch/x86_64/include/vm8086.h |  2 +-
 Kernel/arch/x86_64/mm_phys.c        | 34 ++++++++++++++---------------
 Kernel/drv/dma.c                    |  2 +-
 Kernel/drv/kb.c                     |  4 ++--
 Kernel/drv/pci.c                    |  2 +-
 Kernel/heap.c                       | 10 ++++-----
 Kernel/include/acess.h              |  1 +
 Kernel/include/vfs_ext.h            |  4 ++--
 Kernel/lib.c                        | 10 ++++++---
 Kernel/modules.c                    |  3 ++-
 Kernel/system.c                     |  3 ++-
 Kernel/vfs/fs/devfs.c               |  2 +-
 Kernel/vfs/open.c                   |  2 +-
 15 files changed, 45 insertions(+), 38 deletions(-)

diff --git a/Kernel/arch/x86/include/vm8086.h b/Kernel/arch/x86/include/vm8086.h
index 353ad7a3..7c8dd47d 100644
--- a/Kernel/arch/x86/include/vm8086.h
+++ b/Kernel/arch/x86/include/vm8086.h
@@ -56,7 +56,7 @@ extern void	*VM8086_Allocate(tVM8086 *State, int Size, Uint16 *Segment, Uint16 *
  * \param Offset	Source Offset
  * \return Host pointer to the emulated memory
  */
-extern void *VM8086_GetPointer(tVM8086 *State, Uint16 Segment, Uint16 Ofs);
+extern void *VM8086_GetPointer(tVM8086 *State, Uint16 Segment, Uint16 Offset);
 /**
  * \brief Calls a real-mode interrupt described by the current state of the IVT.
  * \param State	Emulator State
diff --git a/Kernel/arch/x86/time.c b/Kernel/arch/x86/time.c
index c38a9cd4..6a2d0399 100644
--- a/Kernel/arch/x86/time.c
+++ b/Kernel/arch/x86/time.c
@@ -67,8 +67,8 @@ int Time_Setup(void)
 }
 
 /**
- * \fn void Time_Interrupt(void)
  * \brief Called on the timekeeping IRQ
+ * \param irq	IRQ number (unused)
  */
 void Time_Interrupt(int irq)
 {
diff --git a/Kernel/arch/x86_64/include/vm8086.h b/Kernel/arch/x86_64/include/vm8086.h
index 353ad7a3..7c8dd47d 100644
--- a/Kernel/arch/x86_64/include/vm8086.h
+++ b/Kernel/arch/x86_64/include/vm8086.h
@@ -56,7 +56,7 @@ extern void	*VM8086_Allocate(tVM8086 *State, int Size, Uint16 *Segment, Uint16 *
  * \param Offset	Source Offset
  * \return Host pointer to the emulated memory
  */
-extern void *VM8086_GetPointer(tVM8086 *State, Uint16 Segment, Uint16 Ofs);
+extern void *VM8086_GetPointer(tVM8086 *State, Uint16 Segment, Uint16 Offset);
 /**
  * \brief Calls a real-mode interrupt described by the current state of the IVT.
  * \param State	Emulator State
diff --git a/Kernel/arch/x86_64/mm_phys.c b/Kernel/arch/x86_64/mm_phys.c
index c67b9052..0130773f 100644
--- a/Kernel/arch/x86_64/mm_phys.c
+++ b/Kernel/arch/x86_64/mm_phys.c
@@ -307,24 +307,24 @@ void MM_InitPhys_Multiboot(tMBoot_Info *MBoot)
 
 /**
  * \brief Allocate a contiguous range of physical pages with a maximum
- *        bit size of \a Bits
- * \param Num	Number of pages to allocate
- * \param Bits	Maximum size of the physical address
- * \note If \a Bits is <= 0, any sized address is used (with preference
+ *        bit size of \a MaxBits
+ * \param Pages	Number of pages to allocate
+ * \param MaxBits	Maximum size of the physical address
+ * \note If \a MaxBits is <= 0, any sized address is used (with preference
  *       to higher addresses)
  */
-tPAddr MM_AllocPhysRange(int Num, int Bits)
+tPAddr MM_AllocPhysRange(int Pages, int MaxBits)
 {
 	tPAddr	addr, ret;
 	 int	rangeID;
 	 int	nFree = 0, i;
 	
-	ENTER("iNum iBits", Num, Bits);
+	ENTER("iPages iBits", Pages, MaxBits);
 	
-	if( Bits <= 0 || Bits >= 64 )	// Speedup for the common case
+	if( MaxBits <= 0 || MaxBits >= 64 )	// Speedup for the common case
 		rangeID = MM_PHYS_MAX;
 	else
-		rangeID = MM_int_GetRangeID( (1LL << Bits) - 1 );
+		rangeID = MM_int_GetRangeID( (1LL << MaxBits) - 1 );
 	
 	LOG("rangeID = %i", rangeID);
 	
@@ -344,14 +344,14 @@ tPAddr MM_AllocPhysRange(int Num, int Bits)
 		Warning(" MM_AllocPhysRange: Out of free pages");
 		Log_Warning("Arch",
 			"Out of memory (unable to fulfil request for %i pages), zero remaining",
-			Num
+			Pages
 			);
 		LEAVE('i', 0);
 		return 0;
 	}
 	
 	// Check if there is enough in the range
-	if(giPhysRangeFree[rangeID] >= Num)
+	if(giPhysRangeFree[rangeID] >= Pages)
 	{
 		LOG("{%i,0x%x -> 0x%x}",
 			giPhysRangeFree[rangeID],
@@ -389,14 +389,14 @@ tPAddr MM_AllocPhysRange(int Num, int Bits)
 			}
 			nFree ++;
 			addr ++;
-			LOG("nFree(%i) == %i (0x%x)", nFree, Num, addr);
+			LOG("nFree(%i) == %i (0x%x)", nFree, Pages, addr);
 			if(nFree == Num)
 				break;
 		}
 		LOG("nFree = %i", nFree);
 		// If we don't find a contiguous block, nFree will not be equal
 		// to Num, so we set it to zero and do the expensive lookup.
-		if(nFree != Num)	nFree = 0;
+		if(nFree != Pages)	nFree = 0;
 	}
 	
 	if( !nFree )
@@ -420,8 +420,8 @@ tPAddr MM_AllocPhysRange(int Num, int Bits)
 	LOG("nFree = %i, addr = 0x%08x", nFree, addr);
 	
 	// Mark pages as allocated
-	addr -= Num;
-	for( i = 0; i < Num; i++, addr++ )
+	addr -= Pages;
+	for( i = 0; i < Pages; i++, addr++ )
 	{
 		gaMainBitmap[addr >> 6] |= 1LL << (addr & 63);
 		rangeID = MM_int_GetRangeID(addr << 12);
@@ -433,10 +433,10 @@ tPAddr MM_AllocPhysRange(int Num, int Bits)
 	ret = addr;	// Save the return address
 	
 	// Update super bitmap
-	Num += addr & (64-1);
+	Pages += addr & (64-1);
 	addr &= ~(64-1);
-	Num = (Num + (64-1)) & ~(64-1);
-	for( i = 0; i < Num/64; i++ )
+	Pages = (Pages + (64-1)) & ~(64-1);
+	for( i = 0; i < Pages/64; i++ )
 	{
 		if( gaMainBitmap[ addr >> 6 ] + 1 == 0 )
 			gaSuperBitmap[addr>>12] |= 1LL << ((addr >> 6) & 63);
diff --git a/Kernel/drv/dma.c b/Kernel/drv/dma.c
index 56ab7e54..798a3e40 100644
--- a/Kernel/drv/dma.c
+++ b/Kernel/drv/dma.c
@@ -39,8 +39,8 @@ t_dmaChannel	dma_channels[8];
 
 // === CODE ===
 /**
- * \fn int DMA_Install(void)
  * \brief Initialise DMA channels
+ * \param Arguments	Arguments passed at boot time
  */
 int DMA_Install(char **Arguments)
 {
diff --git a/Kernel/drv/kb.c b/Kernel/drv/kb.c
index 28feb05b..923a58fc 100644
--- a/Kernel/drv/kb.c
+++ b/Kernel/drv/kb.c
@@ -54,7 +54,7 @@ Uint8	gbaKB_States[3][256];
 
 // === CODE ===
 /**
- * \fn int KB_Install(char **Arguments)
+ * \brief Install the keyboard driver
  */
 int KB_Install(char **Arguments)
 {
@@ -74,8 +74,8 @@ int KB_Install(char **Arguments)
 }
 
 /**
- * \fn void KB_IRQHandler()
  * \brief Called on a keyboard IRQ
+ * \param IRQNum	IRQ number (unused)
  */
 void KB_IRQHandler(int IRQNum)
 {
diff --git a/Kernel/drv/pci.c b/Kernel/drv/pci.c
index ec96d866..1f9e7285 100644
--- a/Kernel/drv/pci.c
+++ b/Kernel/drv/pci.c
@@ -79,8 +79,8 @@ Uint32	gaPCI_BusBitmap[256/32];
  
 // === CODE ===
 /**
- * \fn int PCI_Install()
  * \brief Scan the PCI Bus for devices
+ * \param Arguments	Boot-time parameters
  */
 int PCI_Install(char **Arguments)
 {
diff --git a/Kernel/heap.c b/Kernel/heap.c
index b55687b8..4c0232e0 100644
--- a/Kernel/heap.c
+++ b/Kernel/heap.c
@@ -441,18 +441,18 @@ void *Heap_Reallocate(const char *File, int Line, void *__ptr, size_t __size)
 }
 
 /**
- * \fn void *Heap_AllocateZero(const char *File, int Line, size_t size)
+ * \fn void *Heap_AllocateZero(const char *File, int Line, size_t Bytes)
  * \brief Allocate and Zero a buffer in memory
  * \param File	Allocating file
  * \param Line	Line of allocation
- * \param size	Size of the allocation
+ * \param Bytes	Size of the allocation
  */
-void *Heap_AllocateZero(const char *File, int Line, size_t size)
+void *Heap_AllocateZero(const char *File, int Line, size_t Bytes)
 {
-	void	*ret = Heap_Allocate(File, Line, size);
+	void	*ret = Heap_Allocate(File, Line, Bytes);
 	if(ret == NULL)	return NULL;
 	
-	memset( ret, 0, size );
+	memset( ret, 0, Bytes );
 	
 	return ret;
 }
diff --git a/Kernel/include/acess.h b/Kernel/include/acess.h
index 9549ede3..e6afcf5e 100644
--- a/Kernel/include/acess.h
+++ b/Kernel/include/acess.h
@@ -262,6 +262,7 @@ extern tPAddr	MM_AllocPhys(void);
 /**
  * \brief Allocate a contiguous range of physical pages
  * \param Pages	Number of pages to allocate
+ * \param MaxBits	Maximum number of address bits allowed
  * \return First physical address allocated
  */
 extern tPAddr	MM_AllocPhysRange(int Pages, int MaxBits);
diff --git a/Kernel/include/vfs_ext.h b/Kernel/include/vfs_ext.h
index cfd69497..1a5fab68 100644
--- a/Kernel/include/vfs_ext.h
+++ b/Kernel/include/vfs_ext.h
@@ -165,10 +165,10 @@ extern int	VFS_ChRoot(char *New);
  * \brief Change the location of the current file pointer
  * \param FD	File handle returned by ::VFS_Open
  * \param Offset	Offset within the file to go to
- * \param Direction	A direction from ::eVFS_SeekDirs
+ * \param Whence	A direction from ::eVFS_SeekDirs
  * \return Boolean success
  */
-extern int	VFS_Seek(int FD, Sint64 Offset, int Direction);
+extern int	VFS_Seek(int FD, Sint64 Offset, int Whence);
 /**
  * \brief Returns the current file pointer
  * \param FD	File handle returned by ::VFS_Open
diff --git a/Kernel/lib.c b/Kernel/lib.c
index b512022d..cab15b3c 100644
--- a/Kernel/lib.c
+++ b/Kernel/lib.c
@@ -687,8 +687,10 @@ Uint rand(void)
 	return giRandomState;
 }
 
-/// \name Memory Validation
-/// \{
+/* *
+ * \name Memory Validation
+ * \{
+ */
 /**
  * \brief Checks if a string resides fully in valid memory
  */
@@ -754,7 +756,9 @@ int CheckMem(void *Mem, int NumBytes)
 	}
 	return 0;
 }
-/// \}
+/* *
+ * \}
+ */
 
 /**
  * \brief Search a string array for \a Needle
diff --git a/Kernel/modules.c b/Kernel/modules.c
index 87511aa6..58521baa 100644
--- a/Kernel/modules.c
+++ b/Kernel/modules.c
@@ -254,7 +254,8 @@ void Modules_LoadBuiltins()
 
 /**
  * \brief Initialise a builtin module given it's name
- * \example Used by VTerm to load an alternate video driver at runtime
+ * 
+ * E.g. Used by VTerm to load an alternate video driver at runtime
  */
 int Modules_InitialiseBuiltin(const char *Name)
 {
diff --git a/Kernel/system.c b/Kernel/system.c
index df9ac414..da1dc92f 100644
--- a/Kernel/system.c
+++ b/Kernel/system.c
@@ -221,7 +221,8 @@ void System_ParseVFS(char *Arg)
 }
 
 /**
- * \biref Parse a module argument string
+ * \brief Parse a module argument string
+ * \param Arg	Argument string
  */
 void System_ParseModuleArgs(char *Arg)
 {
diff --git a/Kernel/vfs/fs/devfs.c b/Kernel/vfs/fs/devfs.c
index 098ac4f6..39745733 100644
--- a/Kernel/vfs/fs/devfs.c
+++ b/Kernel/vfs/fs/devfs.c
@@ -128,7 +128,7 @@ char *DevFS_ReadDir(tVFS_Node *Node, int Pos)
 }
 
 /**
- * \fn tVFS_Node *DevFS_FindDir(tVFS_Node *Node, char *Name)
+ * \fn tVFS_Node *DevFS_FindDir(tVFS_Node *Node, const char *Name)
  * \brief Get an entry from the devices directory
  */
 tVFS_Node *DevFS_FindDir(tVFS_Node *Node, const char *Name)
diff --git a/Kernel/vfs/open.c b/Kernel/vfs/open.c
index 118380fd..3a2622f5 100644
--- a/Kernel/vfs/open.c
+++ b/Kernel/vfs/open.c
@@ -167,7 +167,7 @@ char *VFS_GetAbsPath(const char *Path)
 }
 
 /**
- * \fn char *VFS_ParsePath(char *Path, char **TruePath)
+ * \fn char *VFS_ParsePath(const char *Path, char **TruePath)
  * \brief Parses a path, resolving sysmlinks and applying permissions
  */
 tVFS_Node *VFS_ParsePath(const char *Path, char **TruePath)
-- 
2.20.1