Skip to content

CHAPTER_DOC_STANDARD.md

Latest commit

 

History

History
217 lines (162 loc) · 4.02 KB

CHAPTER_DOC_STANDARD.md

File metadata and controls

217 lines (162 loc) · 4.02 KB
Raw

章节文档规范

每个章节目录必须包含一个 README.md 文件，内容结构如下：

文档结构模板

# 第XX章：章节标题

## 概述

简要介绍本章的学习目标和主要内容（2-3句话）。

## 学习目标

学完本章后，读者将能够：
- 目标1
- 目标2
- 目标3

## 前置知识

阅读本章前，读者需要了解：

### 必备知识
- **第YY章**：XXX（简要说明为什么需要）
- **概念A**：XXX（简要说明）

### 推荐知识
- **概念B**：XXX（可选，帮助理解）

### 预期读者水平
- 熟悉 C 语言编程
- 了解基本的汇编语言
- （其他要求...）

## 核心概念

### 概念1：名称

#### 为什么需要它？
解释这个概念要解决什么问题。

#### 原理说明
详细解释概念的工作原理，可以包含：
- 文字描述
- 图解说明
- 代码示例

#### 数据结构（如果适用）
```c
struct example {
    // 字段说明
};

关键函数/接口

  • function_name()：功能说明

概念2：名称

...

实现细节

文件结构

chapter/
├── boot/
│   ├── mbr.S
│   └── loader.S
├── kernel/
│   ├── include/
│   ├── src/
│   └── kernel.c
└── Makefile

关键代码解析

代码段1：功能名称

// 代码示例

解析：解释这段代码的作用和关键点。

编译和运行

编译命令

cd XX.chapter-name
make all      # 编译
make run      # 运行
make clean    # 清理

预期输出

预期看到的输出示例

调试技巧

常见问题

  1. 问题A：原因和解决方案
  2. 问题B：原因和解决方案

调试方法

  • 如何使用 QEMU 调试
  • 如何查看内存状态
  • 其他调试建议

课后练习

  1. 练习1：描述

    • 难度：简单/中等/困难
    • 提示：XXX

  2. 练习2：描述

    • 难度：简单/中等/困难
    • 提示：XXX

扩展阅读

  • [链接1]：相关资料
  • [链接2]：深入理解

下一章预告

下一章将学习 XXX，需要掌握 XXX 知识。

文档编写原则

1. 循序渐进

  • 从简单概念到复杂概念
  • 每个概念都要解释"为什么"
  • 提供具体例子而非抽象描述

2. 代码量控制

  • 单章节新增代码不超过 500 行
  • 核心功能代码不超过 300 行
  • 辅助代码放在附录或单独文件

3. 图示优先

  • 复杂概念必须有图解
  • 使用 ASCII 图或建议读者使用绘图工具
  • 流程图、结构图、时序图等

4. 实践导向

  • 每个概念都要有可运行的代码
  • 提供完整的编译运行指令
  • 包含预期输出便于验证

5. 错误处理

  • 说明常见错误及原因
  • 提供调试方法
  • 包含错误处理代码示例

文件命名规范

  • 章节目录：XX.chapter-name（两位数字，小写字母，连字符分隔）
  • 文档文件：README.md（必须存在于每个章节目录）
  • 代码文件：使用小写字母和下划线，如 task.c, context_switch.S
  • 头文件：使用小写字母和下划线，如 task.h, scheduler.h

章节划分原则

  1. 单一职责：每个章节只讲解一个核心概念
  2. 独立性：章节之间尽量独立，减少相互依赖
  3. 渐进性：后续章节构建在前面的基础上
  4. 可测试性：每个章节都有可运行的测试代码
  5. 完整性：每个章节完成后，读者能够理解并实现相关功能

图表规范

内存布局图

+------------------+ 高地址
|    栈空间        |
+------------------+
|        ↓         |
|                  |
|        ↑         |
+------------------+
|    堆空间        |
+------------------+
|    数据段        |
+------------------+
|    代码段        |
+------------------+ 低地址

流程图

开始 -> 步骤1 -> 步骤2 -> 结束

数据结构图

task_t
├── tid
├── state
├── priority
└── ctx (cpu_context_t)
    ├── ebx
    ├── esi
    └── edi