@@ -51,35 +51,37 @@ kernel/src/
5151
5252### 注释与文档
5353
54+ 对于注释，我们建议使用英文编写，以确保项目的国际化，使全世界的开发者都能够理解和维护代码。
55+
5456** 单行注释** ：
5557``` rust
56- // 使用简单的注释解释复杂逻辑
57- let frame = allocator . allocate ()? ; // 如果分配失败则返回错误
58+ // Use the simple comment to explain the complex logic
59+ let frame = allocator . allocate ()? ; // If allocation fails, return an error
5860```
5961
6062** 多行注释** ：
6163``` rust
6264/*
63- * 复杂的算法说明
64- * 第二行说明
65+ * Complex algorithm description
66+ * Second line description
6567 */
6668```
6769
6870** 文档注释** ：
6971``` rust
70- /// 分配一个物理帧
72+ /// Allocate a physical frame
7173///
72- /// # 参数
73- /// - `allocator`: 帧分配器实例
74- /// - `count`: 需要分配的帧数
74+ /// # Arguments
75+ /// - `allocator`: The frame allocator instance
76+ /// - `count`: The number of frames to allocate
7577///
76- /// # 返回值
77- /// 返回分配的帧地址，或错误
78+ /// # Returns
79+ /// Returns the address of the allocated frame, or an error
7880///
79- /// # 安全要求
80- /// 调用者必须确保帧分配器已初始化
81+ /// # Safety Requirements
82+ /// The caller must ensure that the frame allocator is initialized
8183///
82- /// # 示例
84+ /// # Examples
8385/// ```
8486/// let frame = allocate_frames(&mut allocator, 1)?;
8587/// ```
@@ -90,7 +92,7 @@ pub fn allocate_frames(allocator: &mut FrameAllocator, count: usize) -> Result<F
9092
9193** 内联汇编注释** ：
9294``` rust
93- // SAFETY: 必须确保内存对齐和权限正确
95+ // SAFETY: Must ensure that the page table address is valid and properly aligned
9496unsafe {
9597 asm! (" mov cr3, {}" in (reg ) page_table_addr );
9698}
@@ -109,15 +111,18 @@ unsafe {
109111
110112** 示例** ：
111113``` rust
112- /// 设置当前页表
114+ /// Set the current page table
115+ ///
116+ /// # Arguments
117+ /// - `page_table_addr`: The address of the page table to set as the current page table
113118///
114- /// # 安全要求
115- /// - `page_table_addr` 必须指向有效的页表
116- /// - 页表必须正确设置权限位
117- /// - 调用者必须确保在此函数后不会访问无效内存
119+ /// # Safety Requirements
120+ /// - `page_table_addr` must point to a valid page table
121+ /// - The page table must have the correct permission bits set
122+ /// - The caller must ensure that no invalid memory will be accessed after this function returns
118123pub unsafe fn set_page_table (page_table_addr : usize ) {
119- // SAFETY: 调用者必须确保 page_table_addr 指向有效的页表结构，
120- // 并且在切换页表后不会立即访问可能无效的内存地址
124+ // SAFETY: The caller must ensure that ` page_table_addr` points to a valid page table structure,
125+ // and that no invalid memory will be accessed after this function returns.
121126 asm! (" mov cr3, {}" in (reg ) page_table_addr );
122127}
123128```
@@ -153,11 +158,56 @@ pub unsafe fn set_page_table(page_table_addr: usize) {
153158### 测试要求
154159
155160** 单元测试** ：
156- - Rust: 使用 ` #[test ] ` 属性
161+ - Rust: 使用 ` #[test_case ] ` 属性，即在测试函数前添加 ` #[test_case] ` 宏（ ** 不是 ` #[test] ` !!! ** ）
157162
158163** 测试文件位置** ：
159164- Rust 测试与源码在同一文件（使用 ` #[cfg(test)] ` ）
160165
166+ ** 示例** ：
167+ ``` rust
168+ // 这里假定你是在proka-kernel(lib/main)下写的代码，即kernel/src/lib.rs已经
169+ // mod了你的module。
170+ //
171+ // 此时你便可以直接使用`#[test_case]`宏来编写测试用例。
172+
173+ // 这里定义一个功能
174+ pub struct MyStruct {
175+ pub field : u32 ,
176+ }
177+
178+ impl MyStruct {
179+ /// Initilaize a new `MyStruct` with the given field value.
180+ pub fn new (field : u32 ) -> Self {
181+ Self { field }
182+ }
183+
184+ /// Return the value of the `field` field.
185+ pub fn some_method (& self ) -> u32 {
186+ self . field
187+ }
188+ }
189+
190+ // 这里编写测试用例
191+ #[cfg(test)]
192+ mod tests {
193+ use super :: * ;
194+
195+ /// Test the `new` method.
196+ #[test_case]
197+ fn test_new () {
198+ let my_struct = MyStruct :: new (114514 );
199+ assert_eq! (my_struct . field, 114514 );
200+ }
201+
202+ /// Test the `some_method` method.
203+ #[test_case]
204+ fn test_some_method () {
205+ let my_struct = MyStruct :: new (114514 );
206+ assert_eq! (my_struct . some_method (), 114514 );
207+ }
208+ }
209+ ```
210+
161211---
162212
163213## 总结
0 commit comments