Docs: Change comment styles

Zhuagenborn · Oct 22, 2024 · 116f5e7 · 116f5e7
1 parent 425021f
commit 116f5e7
Show file tree

Hide file tree

Showing 49 changed files with 602 additions and 198 deletions.
diff --git a/README.md b/README.md
@@ -66,6 +66,229 @@ This project is a tiny *Intel x86* operating system written in *assembly* and *C
 
 - [*《操作系统真象还原》郑钢*](https://github.com/yifengyou/os-elephant)
 
+## Structure
+
+```console
+.
+├── CITATION.cff
+├── Debugging.md
+├── LICENSE
+├── Makefile
+├── README.md
+├── docs
+│   ├── Boot
+│   │   ├── Images
+│   │   │   └── loader
+│   │   │       ├── memory-paging.drawio
+│   │   │       ├── memory-paging.svg
+│   │   │       ├── page-directory-table.drawio
+│   │   │       └── page-directory-table.svg
+│   │   ├── Loader.md
+│   │   └── Master Boot Record.md
+│   ├── Getting Started
+│   │   ├── Building the System.md
+│   │   └── Development Environment.md
+│   ├── Kernel
+│   │   ├── File System.md
+│   │   ├── Images
+│   │   │   ├── file-system
+│   │   │   │   ├── directory-entries.drawio
+│   │   │   │   ├── directory-entries.svg
+│   │   │   │   ├── index-node.drawio
+│   │   │   │   └── index-node.svg
+│   │   │   ├── memory
+│   │   │   │   ├── memory-heap.drawio
+│   │   │   │   ├── memory-heap.svg
+│   │   │   │   ├── memory-pools.drawio
+│   │   │   │   └── memory-pools.svg
+│   │   │   └── threads
+│   │   │       ├── thread-block.drawio
+│   │   │       ├── thread-block.svg
+│   │   │       ├── thread-lists.drawio
+│   │   │       ├── thread-lists.svg
+│   │   │       ├── thread-switching.drawio
+│   │   │       └── thread-switching.svg
+│   │   ├── Interrupts.md
+│   │   ├── Memory.md
+│   │   ├── System Calls.md
+│   │   ├── Threads.md
+│   │   └── User Processes.md
+│   └── badges
+│       ├── C++.svg
+│       ├── License-MIT.svg
+│       ├── Linux.svg
+│       ├── Made-with-GitHub-Actions.svg
+│       ├── Made-with-Make.svg
+│       └── NASM.svg
+├── include
+│   ├── boot
+│   │   └── boot.inc
+│   ├── kernel
+│   │   ├── debug
+│   │   │   └── assert.h
+│   │   ├── descriptor
+│   │   │   ├── desc.h
+│   │   │   ├── desc.inc
+│   │   │   └── gdt
+│   │   │       ├── idx.h
+│   │   │       └── tab.h
+│   │   ├── interrupt
+│   │   │   ├── intr.h
+│   │   │   └── pic.h
+│   │   ├── io
+│   │   │   ├── disk
+│   │   │   │   ├── disk.h
+│   │   │   │   ├── disk.inc
+│   │   │   │   ├── file
+│   │   │   │   │   ├── dir.h
+│   │   │   │   │   ├── file.h
+│   │   │   │   │   ├── inode.h
+│   │   │   │   │   └── super_block.h
+│   │   │   │   └── ide.h
+│   │   │   ├── file
+│   │   │   │   ├── dir.h
+│   │   │   │   ├── file.h
+│   │   │   │   └── path.h
+│   │   │   ├── io.h
+│   │   │   ├── keyboard.h
+│   │   │   ├── timer.h
+│   │   │   └── video
+│   │   │       ├── console.h
+│   │   │       ├── print.h
+│   │   │       └── print.inc
+│   │   ├── krnl.h
+│   │   ├── krnl.inc
+│   │   ├── memory
+│   │   │   ├── page.h
+│   │   │   ├── page.inc
+│   │   │   └── pool.h
+│   │   ├── process
+│   │   │   ├── elf.inc
+│   │   │   ├── proc.h
+│   │   │   └── tss.h
+│   │   ├── selector
+│   │   │   ├── sel.h
+│   │   │   └── sel.inc
+│   │   ├── stl
+│   │   │   ├── algorithm.h
+│   │   │   ├── array.h
+│   │   │   ├── cerron.h
+│   │   │   ├── cmath.h
+│   │   │   ├── cstddef.h
+│   │   │   ├── cstdint.h
+│   │   │   ├── cstdlib.h
+│   │   │   ├── cstring.h
+│   │   │   ├── iterator.h
+│   │   │   ├── mutex.h
+│   │   │   ├── semaphore.h
+│   │   │   ├── source_location.h
+│   │   │   ├── span.h
+│   │   │   ├── string_view.h
+│   │   │   ├── type_traits.h
+│   │   │   └── utility.h
+│   │   ├── syscall
+│   │   │   └── call.h
+│   │   ├── thread
+│   │   │   ├── sync.h
+│   │   │   └── thd.h
+│   │   └── util
+│   │       ├── bit.h
+│   │       ├── bitmap.h
+│   │       ├── block_queue.h
+│   │       ├── format.h
+│   │       ├── metric.h
+│   │       ├── metric.inc
+│   │       └── tag_list.h
+│   └── user
+│       ├── io
+│       │   ├── file
+│       │   │   ├── dir.h
+│       │   │   └── file.h
+│       │   └── video
+│       │       └── console.h
+│       ├── memory
+│       │   └── pool.h
+│       ├── process
+│       │   └── proc.h
+│       ├── stl
+│       │   └── cstdint.h
+│       └── syscall
+│           └── call.h
+└── src
+    ├── boot
+    │   ├── loader.asm
+    │   └── mbr.asm
+    ├── kernel
+    │   ├── debug
+    │   │   └── assert.cpp
+    │   ├── descriptor
+    │   │   ├── desc.asm
+    │   │   └── gdt
+    │   │       └── tab.cpp
+    │   ├── interrupt
+    │   │   ├── intr.asm
+    │   │   ├── intr.cpp
+    │   │   └── pic.cpp
+    │   ├── io
+    │   │   ├── disk
+    │   │   │   ├── disk.cpp
+    │   │   │   ├── file
+    │   │   │   │   ├── dir.cpp
+    │   │   │   │   ├── file.cpp
+    │   │   │   │   ├── inode.cpp
+    │   │   │   │   └── super_block.cpp
+    │   │   │   ├── ide.cpp
+    │   │   │   └── part.cpp
+    │   │   ├── file
+    │   │   │   ├── dir.cpp
+    │   │   │   ├── file.cpp
+    │   │   │   └── path.cpp
+    │   │   ├── io.asm
+    │   │   ├── io.cpp
+    │   │   ├── keyboard.cpp
+    │   │   ├── timer.cpp
+    │   │   └── video
+    │   │       ├── console.cpp
+    │   │       ├── print.asm
+    │   │       └── print.cpp
+    │   ├── krnl.cpp
+    │   ├── main.cpp
+    │   ├── memory
+    │   │   ├── page.asm
+    │   │   ├── page.cpp
+    │   │   └── pool.cpp
+    │   ├── process
+    │   │   ├── proc.cpp
+    │   │   ├── tss.asm
+    │   │   └── tss.cpp
+    │   ├── stl
+    │   │   ├── cstring.cpp
+    │   │   ├── mutex.cpp
+    │   │   └── semaphore.cpp
+    │   ├── syscall
+    │   │   ├── call.asm
+    │   │   └── call.cpp
+    │   ├── thread
+    │   │   ├── sync.cpp
+    │   │   ├── thd.asm
+    │   │   └── thd.cpp
+    │   └── util
+    │       ├── bitmap.cpp
+    │       ├── format.cpp
+    │       └── tag_list.cpp
+    └── user
+        ├── io
+        │   ├── file
+        │   │   ├── dir.cpp
+        │   │   └── file.cpp
+        │   └── video
+        │       └── console.cpp
+        ├── memory
+        │   └── pool.cpp
+        └── process
+            └── proc.cpp
+```
+
 ## License
 
 Distributed under the *MIT License*. See `LICENSE` for more information.
diff --git a/include/kernel/debug/assert.h b/include/kernel/debug/assert.h
@@ -1,5 +1,9 @@
 /**
- * Diagnostics tools.
+ * @file assert.h
+ * @brief  * Diagnostics tools.
+ *
+ * @par GitHub
+ * https://github.com/Zhuagenborn
  */
 
 #pragma once

diff --git a/include/kernel/descriptor/desc.h b/include/kernel/descriptor/desc.h
@@ -1,5 +1,9 @@
 /**
- * Descriptors.
+ * @file desc.h
+ * @brief Descriptors.
+ *
+ * @par GitHub
+ * https://github.com/Zhuagenborn
  */
 
 #pragma once
@@ -62,7 +66,9 @@ enum class NonSysType {
 };
 
 /**
- * The descriptor attribute.
+ * @brief The descriptor attribute.
+ *
+ * @details
  * It is located in the bits `40`-`47` of a descriptor.
  */
 class Attribute {
@@ -240,7 +246,9 @@ class Descriptor {
 static_assert(sizeof(Descriptor) == sizeof(stl::uint64_t));
 
 /**
- * The gate descriptor.
+ * @brief The gate descriptor.
+ *
+ * @details
  * There are four types of gate descriptors:
  * - The task gate descriptor.
  * - The call gate descriptor.
@@ -309,13 +317,13 @@ class GateDesc : public Descriptor {
 static_assert(sizeof(GateDesc) == sizeof(stl::uint64_t));
 
 /**
- * @brief
- * The segment descriptor.
+ * @brief The segment descriptor.
+ *
+ * @details
  * It is a part of memory segmentation, used for translating a logical address into a linear address.
  * It describes the memory segment referred to in the logical address.
  *
- * @details
- * ```
+ * @code
  * --------------------------------------------- High 32 bits ---------------------------------------------
  *      31-24    23   22   21   20       19-16     15  14-13  12  11-8       7-0
  * ┌────────────┬───┬─────┬───┬─────┬─────────────┬───┬─────┬───┬──────┬────────────┐
@@ -338,7 +346,7 @@ static_assert(sizeof(GateDesc) == sizeof(stl::uint64_t));
  * ┌───────────┬────────────┐
  * │ Base 15-0 │ Limit 15-0 │
  * └───────────┴────────────┘
- * ```
+ * @endcode
  */
 class SegDesc : public Descriptor {
 public:
@@ -435,7 +443,9 @@ static_assert(sizeof(SegDesc) == sizeof(stl::uint64_t));
 #pragma pack(push, 1)
 
 /**
- * The descriptor table register.
+ * @brief The descriptor table register.
+ *
+ * @details
  * They store the location of a descriptor table.
  */
 class DescTabReg {
@@ -505,9 +515,7 @@ class DescTab {
     virtual const T& GetDesc(stl::size_t) const noexcept = 0;
 };
 
-/**
- * The descriptor table that refers to a contiguous sequence of descriptors.
- */
+//! The descriptor table that refers to a contiguous sequence of descriptors.
 template <typename T>
 class DescTabSpan : public DescTab<T> {
 public:
@@ -531,9 +539,7 @@ class DescTabSpan : public DescTab<T> {
     T* descs_;
 };
 
-/**
- * The descriptor table that uses a built-in array to store descriptors.
- */
+//! The descriptor table that uses a built-in array to store descriptors.
 template <typename T, stl::size_t count>
 class DescTabArray : public DescTab<T> {
 public:

diff --git a/include/kernel/descriptor/gdt/idx.h b/include/kernel/descriptor/gdt/idx.h
@@ -1,5 +1,9 @@
 /**
- * Global descriptor indexes.
+ * @file idx.h
+ * @brief Global descriptor indexes.
+ *
+ * @par GitHub
+ * https://github.com/Zhuagenborn
  */
 
 #pragma once

diff --git a/include/kernel/descriptor/gdt/tab.h b/include/kernel/descriptor/gdt/tab.h
@@ -1,5 +1,9 @@
 /**
- * The global descriptor table.
+ * @file tab.h
+ * @brief The global descriptor table.
+ *
+ * @par GitHub
+ * https://github.com/Zhuagenborn
  */
 
 #pragma once