From 72a03f641d1239b3dfb630015e65ebcedf0bd588 Mon Sep 17 00:00:00 2001 From: Aiken Harris Date: Wed, 20 May 2026 20:52:52 +0200 Subject: [PATCH] Update doxygen comments and formatting --- xtoskrnl/ke/apc.cc | 2 +- xtoskrnl/ke/bootinfo.cc | 4 ++-- xtoskrnl/ke/dpc.cc | 10 +++++----- xtoskrnl/ke/event.cc | 6 +++--- xtoskrnl/ke/kprocess.cc | 9 ++++++++- xtoskrnl/ke/kthread.cc | 13 ++++++++++--- xtoskrnl/ke/semphore.cc | 4 ++-- xtoskrnl/ke/spinlock.cc | 2 +- xtoskrnl/ke/sysres.cc | 6 +++--- xtoskrnl/ke/timer.cc | 4 ++-- xtoskrnl/mm/alloc.cc | 22 +++++++++++----------- xtoskrnl/mm/amd64/pagemap.cc | 4 ++-- xtoskrnl/mm/amd64/paging.cc | 2 +- xtoskrnl/mm/amd64/pfault.cc | 2 ++ xtoskrnl/mm/hlpool.cc | 8 ++++---- xtoskrnl/mm/i686/pagemap.cc | 10 +++++----- xtoskrnl/mm/i686/paging.cc | 2 +- xtoskrnl/mm/kpool.cc | 4 ++-- xtoskrnl/mm/mmgr.cc | 2 +- xtoskrnl/mm/paging.cc | 6 +++--- xtoskrnl/mm/pfn.cc | 2 +- xtoskrnl/po/idle.cc | 4 ++-- 22 files changed, 72 insertions(+), 56 deletions(-) diff --git a/xtoskrnl/ke/apc.cc b/xtoskrnl/ke/apc.cc index 9147aa3..1969d5c 100644 --- a/xtoskrnl/ke/apc.cc +++ b/xtoskrnl/ke/apc.cc @@ -38,7 +38,7 @@ * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID diff --git a/xtoskrnl/ke/bootinfo.cc b/xtoskrnl/ke/bootinfo.cc index 937d099..e572d46 100644 --- a/xtoskrnl/ke/bootinfo.cc +++ b/xtoskrnl/ke/bootinfo.cc @@ -46,7 +46,7 @@ KE::BootInformation::GetFirmwareType(VOID) * @param Parameter * Supplies a pointer to a variable that receives a pointer to the matching parameter, or NULLPTR if not found. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -116,7 +116,7 @@ KE::BootInformation::GetKernelParameter(IN PCWSTR ParameterName, * @param BufferSize * Supplies the size of the value buffer, in wide characters. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/ke/dpc.cc b/xtoskrnl/ke/dpc.cc index f0f707d..396fad7 100644 --- a/xtoskrnl/ke/dpc.cc +++ b/xtoskrnl/ke/dpc.cc @@ -23,7 +23,7 @@ * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID @@ -56,7 +56,7 @@ KE::Dpc::InitializeDpc(IN PKDPC Dpc, * * @return This routine does not return any value. * - * @since NT 5.2 + * @since XT 1.0 */ XTAPI VOID @@ -86,7 +86,7 @@ KE::Dpc::InitializeThreadedDpc(IN PKDPC Dpc, * * @return This routine does not return any value. * - * @since NT 4.0 + * @since XT 1.0 */ XTAPI VOID @@ -104,7 +104,7 @@ KE::Dpc::SetTargetProcessor(IN PKDPC Dpc, * * @return This routine does not return any value. * - * @since NT 5.2 + * @since XT 1.0 */ XTAPI VOID @@ -121,7 +121,7 @@ KE::Dpc::SignalCallDone(IN PVOID SystemArgument) * * @return This routine returns TRUE if just one processor is waiting on the barrier, FALSE if more. * - * @since NT 5.2 + * @since XT 1.0 */ XTAPI BOOLEAN diff --git a/xtoskrnl/ke/event.cc b/xtoskrnl/ke/event.cc index df7085c..83b4020 100644 --- a/xtoskrnl/ke/event.cc +++ b/xtoskrnl/ke/event.cc @@ -17,7 +17,7 @@ * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID @@ -41,7 +41,7 @@ KE::Event::ClearEvent(IN PKEVENT Event) * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID @@ -71,7 +71,7 @@ KE::Event::InitializeEvent(OUT PKEVENT Event, * * @return This routine returns the previous signal state of the event. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI LONG diff --git a/xtoskrnl/ke/kprocess.cc b/xtoskrnl/ke/kprocess.cc index d04a620..ac60e85 100644 --- a/xtoskrnl/ke/kprocess.cc +++ b/xtoskrnl/ke/kprocess.cc @@ -9,6 +9,13 @@ #include +/** + * Retrieves a pointer to the system's initial executive process object. + * + * @return This routine returns a pointer to the initial executive process. + * + * @since XT 1.0 + */ XTAPI PEPROCESS KE::KProcess::GetInitialProcess(VOID) @@ -36,7 +43,7 @@ KE::KProcess::GetInitialProcess(VOID) * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID diff --git a/xtoskrnl/ke/kthread.cc b/xtoskrnl/ke/kthread.cc index 55b3e64..39c2533 100644 --- a/xtoskrnl/ke/kthread.cc +++ b/xtoskrnl/ke/kthread.cc @@ -9,6 +9,13 @@ #include +/** + * Retrieves a pointer to the system's initial executive thread object. + * + * @return This routine returns a pointer to the initial executive thread. + * + * @since XT 1.0 + */ XTAPI PETHREAD KE::KThread::GetInitialThread(VOID) @@ -43,9 +50,9 @@ KE::KThread::GetInitialThread(VOID) * @param Stack * Supplies a pointer to the stack of the thread. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI XTSTATUS @@ -189,7 +196,7 @@ KE::KThread::InitializeThread(IN PKPROCESS Process, * * @return This routine does not return any value. * - * @since NT 5.1 + * @since XT 1.0 */ XTAPI VOID diff --git a/xtoskrnl/ke/semphore.cc b/xtoskrnl/ke/semphore.cc index ff0c44c..d5c078c 100644 --- a/xtoskrnl/ke/semphore.cc +++ b/xtoskrnl/ke/semphore.cc @@ -23,7 +23,7 @@ * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID @@ -75,7 +75,7 @@ KE::Semaphore::ReadState(IN PKSEMAPHORE Semaphore) * * @return This routine returns a previous signal state of the semaphore. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI LONG diff --git a/xtoskrnl/ke/spinlock.cc b/xtoskrnl/ke/spinlock.cc index 3e0e2c5..68ddc2c 100644 --- a/xtoskrnl/ke/spinlock.cc +++ b/xtoskrnl/ke/spinlock.cc @@ -137,7 +137,7 @@ KE::SpinLock::InitializeLockQueues() * * @return This routine does not return any value. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI VOID diff --git a/xtoskrnl/ke/sysres.cc b/xtoskrnl/ke/sysres.cc index a5ecc44..8b0d0cb 100644 --- a/xtoskrnl/ke/sysres.cc +++ b/xtoskrnl/ke/sysres.cc @@ -18,7 +18,7 @@ * @param ResourceHeader * Specifies a memory area where a pointer to the system resource header will be stored. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -131,7 +131,7 @@ KE::SystemResources::GetSystemResource(IN SYSTEM_RESOURCE_TYPE ResourceType, * @param ResourceHeader * Specifies a memory area where a pointer to the system resource header will be stored. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -147,7 +147,7 @@ KE::SystemResources::GetResource(IN SYSTEM_RESOURCE_TYPE ResourceType, /** * Initializes system resource management. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/ke/timer.cc b/xtoskrnl/ke/timer.cc index 911d4c7..73d9d66 100644 --- a/xtoskrnl/ke/timer.cc +++ b/xtoskrnl/ke/timer.cc @@ -17,7 +17,7 @@ * * @return This routine returns TRUE if the cancelled timer was set, or FALSE otherwise. * - * @since NT 3.5 + * @since XT 1.0 */ XTAPI BOOLEAN @@ -57,7 +57,7 @@ KE::Timer::CancelTimer(IN PKTIMER Timer) * * @return This routine does not return any value. * - * @since NT 4.0 + * @since XT 1.0 */ XTAPI VOID diff --git a/xtoskrnl/mm/alloc.cc b/xtoskrnl/mm/alloc.cc index eb01bf5..e489b80 100644 --- a/xtoskrnl/mm/alloc.cc +++ b/xtoskrnl/mm/alloc.cc @@ -18,7 +18,7 @@ * @param Memory * Supplies a pointer to the allocated pool of pages. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -192,7 +192,7 @@ MM::Allocator::AllocateNonPagedPoolPages(IN PFN_COUNT Pages, * @param Memory * Supplies a pointer to the allocated pool of pages. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -219,7 +219,7 @@ MM::Allocator::AllocatePagedPoolPages(IN PFN_COUNT Pages, * @param Memory * Supplies a pointer to the allocated pool of pages. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -271,7 +271,7 @@ MM::Allocator::AllocatePages(IN MMPOOL_TYPE PoolType, * @param Memory * Supplies a pointer to the allocated memory. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -300,7 +300,7 @@ MM::Allocator::AllocatePool(IN MMPOOL_TYPE PoolType, * @param Tag * Specifies the allocation identifying tag. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -737,7 +737,7 @@ MM::Allocator::ExpandBigAllocationsTable(VOID) * @param PagesFreed * Supplies a pointer to a variable that will receive the number of pages freed. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -985,7 +985,7 @@ MM::Allocator::FreeNonPagedPoolPages(IN PVOID VirtualAddress, * @param PagesFreed * Supplies a pointer to a variable that will receive the number of pages freed. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -1006,7 +1006,7 @@ MM::Allocator::FreePagedPoolPages(IN PVOID VirtualAddress, * @param VirtualAddress * Supplies the base virtual address of the pages allocation to free. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -1026,7 +1026,7 @@ MM::Allocator::FreePages(IN PVOID VirtualAddress) * @param PagesFreed * Supplies a pointer to a variable that will receive the number of pages freed. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -1059,7 +1059,7 @@ MM::Allocator::FreePages(IN PVOID VirtualAddress, * @param VirtualAddress * Supplies the base virtual address of the pool allocation to free. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -1080,7 +1080,7 @@ MM::Allocator::FreePool(IN PVOID VirtualAddress) * @param Tag * Specifies the allocation identifying tag. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/amd64/pagemap.cc b/xtoskrnl/mm/amd64/pagemap.cc index a56c112..932a447 100644 --- a/xtoskrnl/mm/amd64/pagemap.cc +++ b/xtoskrnl/mm/amd64/pagemap.cc @@ -18,7 +18,7 @@ * @param Count * The number of PTE entries to advance by. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ @@ -96,7 +96,7 @@ MM::PageMap::GetNextEntry(IN PMMPTE Pte) * @param Pte * The PTE pointer to advance. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/amd64/paging.cc b/xtoskrnl/mm/amd64/paging.cc index 694a35e..ef9bd50 100644 --- a/xtoskrnl/mm/amd64/paging.cc +++ b/xtoskrnl/mm/amd64/paging.cc @@ -109,7 +109,7 @@ MM::Paging::GetPxeVirtualAddress(IN PMMPXE PxePointer) * @param Attributes * Specifies the attributes (protections, caching) to apply to the PTE. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/amd64/pfault.cc b/xtoskrnl/mm/amd64/pfault.cc index a3d5b9d..a22dd04 100644 --- a/xtoskrnl/mm/amd64/pfault.cc +++ b/xtoskrnl/mm/amd64/pfault.cc @@ -16,6 +16,8 @@ * Specifies the virtual address to verify. * * @return This routine returns ACCESS_VIOLATION regardless PML4 or PML5 is used. + * + * @since XT 1.0 */ XTFASTCALL XTSTATUS diff --git a/xtoskrnl/mm/hlpool.cc b/xtoskrnl/mm/hlpool.cc index 7935c97..c57ef3f 100644 --- a/xtoskrnl/mm/hlpool.cc +++ b/xtoskrnl/mm/hlpool.cc @@ -25,7 +25,7 @@ * @param Buffer * Supplies a buffer that receives the physical address. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -153,7 +153,7 @@ MM::HardwarePool::AllocateHardwareMemory(IN PFN_NUMBER PageCount, * @param MemoryAddress * Supplies a pointer to a variable that receives the identity-mapped virtual address of the allocated memory. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -207,7 +207,7 @@ MM::HardwarePool::AllocateRealModeMemory(IN PFN_NUMBER PageCount, * @param VirtualAddress * Supplies a buffer that receives the virtual address of the mapped pages. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -374,7 +374,7 @@ MM::HardwarePool::RemapHardwareMemory(IN PVOID VirtualAddress, * @param FlushTlb * Specifies whether to flush the TLB or not. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/i686/pagemap.cc b/xtoskrnl/mm/i686/pagemap.cc index aa1d609..9fe00e5 100644 --- a/xtoskrnl/mm/i686/pagemap.cc +++ b/xtoskrnl/mm/i686/pagemap.cc @@ -251,7 +251,7 @@ MM::PageMapBasic::GetNextEntry(IN PMMPTE Pte) * @param Pte * The PTE pointer to advance. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ @@ -472,7 +472,7 @@ MM::PageMapBasic::InitializePageMapInfo(VOID) * @param PtePointer * Pointer to the page table entry (PTE) to check. * - * @return Returns TRUE if the entry is valid, FALSE otherwise. + * @return This routine returns TRUE if the entry is valid, FALSE otherwise. * * @since XT 1.0 */ @@ -666,7 +666,7 @@ MM::PageMapBasic::WritePte(IN PMMPTE Pte, * @param Count * The number of PTE entries to advance by. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ @@ -721,7 +721,7 @@ MM::PageMapXpa::GetNextEntry(IN PMMPTE Pte) * @param Pte * The PTE pointer to advance. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ @@ -942,7 +942,7 @@ MM::PageMapXpa::InitializePageMapInfo(VOID) * @param PtePointer * Pointer to the page table entry (PTE) to check. * - * @return Returns TRUE if the entry is valid, FALSE otherwise. + * @return This routine returns TRUE if the entry is valid, FALSE otherwise. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/i686/paging.cc b/xtoskrnl/mm/i686/paging.cc index 335d934..f797408 100644 --- a/xtoskrnl/mm/i686/paging.cc +++ b/xtoskrnl/mm/i686/paging.cc @@ -37,7 +37,7 @@ MM::Paging::GetExtendedPhysicalAddressingStatus(VOID) * @param Attributes * Specifies the attributes (protections, caching) to apply to the PTE. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/kpool.cc b/xtoskrnl/mm/kpool.cc index 1673ac6..0c49dfd 100644 --- a/xtoskrnl/mm/kpool.cc +++ b/xtoskrnl/mm/kpool.cc @@ -19,7 +19,7 @@ * @param StackSize * Supplies the size of the stack to be allocated, in bytes. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ @@ -95,7 +95,7 @@ MM::KernelPool::AllocateKernelStack(OUT PVOID *Stack, * @param StructuresData * Supplies a pointer to the memory area that will contain the allocated buffer. * - * @return This routine returns a status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/mmgr.cc b/xtoskrnl/mm/mmgr.cc index 53eaf64..b854db6 100644 --- a/xtoskrnl/mm/mmgr.cc +++ b/xtoskrnl/mm/mmgr.cc @@ -285,7 +285,7 @@ MM::Manager::InitializeMemoryManager(VOID) /** * Allocates and maps the Kernel Shared Data page to its hardcoded virtual address. * - * @return This routine returns status code. + * @return This routine returns a status code indicating the success or failure of the operation. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/paging.cc b/xtoskrnl/mm/paging.cc index 1aa39ca..fb56317 100644 --- a/xtoskrnl/mm/paging.cc +++ b/xtoskrnl/mm/paging.cc @@ -18,7 +18,7 @@ * @param Count * The number of PTE entries to advance by. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ @@ -158,7 +158,7 @@ MM::Paging::GetNextEntry(IN PMMPTE Pte) * @param Pte * The PTE pointer to advance. * - * @return The advanced PTE pointer. + * @return This routine returns the advanced PTE pointer. * * @since XT 1.0 */ @@ -517,7 +517,7 @@ MM::Paging::InitializePageMapSupport(VOID) * @param PtePointer * Pointer to the page table entry (PTE) to check. * - * @return Returns TRUE if the entry is valid, FALSE otherwise. + * @return This routine returns TRUE if the entry is valid, FALSE otherwise. * * @since XT 1.0 */ diff --git a/xtoskrnl/mm/pfn.cc b/xtoskrnl/mm/pfn.cc index 5aa64d8..5e8afee 100644 --- a/xtoskrnl/mm/pfn.cc +++ b/xtoskrnl/mm/pfn.cc @@ -390,7 +390,7 @@ MM::Pfn::GetHighestPhysicalPage(VOID) /** * Retrieves the total number of physical pages managed by the system. * - * @return Returns the total count of physical memory pages. + * @return This routine returns the total count of physical memory pages. * * @since XT 1.0 */ diff --git a/xtoskrnl/po/idle.cc b/xtoskrnl/po/idle.cc index 6380f97..8f9aeba 100644 --- a/xtoskrnl/po/idle.cc +++ b/xtoskrnl/po/idle.cc @@ -63,7 +63,7 @@ PO::Idle::Idle0Function(IN PPROCESSOR_POWER_STATE PowerState) * * @return This routine does not return any value. * - * @since NT 5.1 + * @since XT 1.0 */ XTAPI VOID @@ -89,7 +89,7 @@ PO::Idle::PerfIdle(PPROCESSOR_POWER_STATE PowerState) * * @return This routine does not return any value. * - * @since NT 5.1 + * @since XT 1.0 */ XTAPI VOID