# 撰写总则

## 目录

- [文档分三类](#文档分三类)
- [每篇文档都写目录](#每篇文档都写目录)
- [图中只用项目词条](#图中只用项目词条)
- [图只画本层](#图只画本层)
- [功能模块何时拆开](#功能模块何时拆开)
- [文件名](#文件名)
- [示例与正式文档](#示例与正式文档)

## 文档分三类


| 文档   | 位置                                 | 正文                                       |
| ---- | ---------------------------------- | ---------------------------------------- |
| 项目架构 | `doc/项目架构.md`，全库一篇                 | 目录结构（到 `features/[feature]`）、模块定义、功能模块之间的业务数据流 |
| 基础应用 | `doc/基础应用/`，`src/app` 下，一个目录一篇     | 功能定义、使用示例、该应用内部的数据流与时序                       |
| 功能模块 | `doc/功能模块/`，`src/features` 下一个目录一组 | 模块内目录、功能定义、核心业务层与核心模型、核心业务时序图                |


`src/app` 下的每个目录是一个基础应用。`src/features` 下的每个目录是一个功能模块。

章节的写法分别见：

- [项目架构文档撰写说明](./项目架构文档撰写说明.md)
- [基础应用文档撰写说明](./基础应用/基础应用文档撰写说明.md)
- [功能模块文档撰写说明](./功能模块/功能模块文档撰写说明.md)

## 每篇文档都写目录

标题下第一段是目录，标题为「目录」。条目与正文标题一致，并链到对应标题。拆出去的业务文档写进父文档目录，链到文件。

撰写说明、示例、正式文档都要有目录。

## 图中只用项目词条

Mermaid 的节点、参与者、箭头文字只用仓库里的目录名、类名、方法名、字段名。中文说明写在图外的正文里。

## 图只画本层

项目架构只画 `home`、`security`、`project`、`editor` 之间的业务数据。不画 `session`、`network`、`db`、`routes` 这些基础应用，也不画时序。

基础应用只画该目录内部的类和函数。不画功能模块的调用链，也不把其他基础应用的内部步骤画进来。调用方可以出现在使用示例的代码里。时序图已经能说明这条行为时，不再画数据流图。

功能模块的时序写在功能模块文档。那里不展开基础应用内部步骤。

## 功能模块何时拆开

一条主业务时，时序图写在该模块主文档里。

同一模块有多条要分开讲述的事件业务时，为每条业务另写一篇，放在该模块目录下。主文档保留目录结构、功能定义、核心业务层与核心模型，并用目录链到各业务文档。编辑器的打开、绘制、撤销与重做按这个方式拆开。

方法定义写在主文档的核心业务层。业务文档写该业务的定义和时序图，并点名用到的方法。

## 文件名

- 基础应用：`中文名(目录名).md`，例如 `会话(session).md`。
- 功能模块主文档：`模块名(目录名).md`，例如 `编辑器模块(editor).md`。
- 拆出的业务文档：放在同一模块目录，用业务名作文件名，例如 `绘制.md`。
- 说明与示例只放在 `doc/文档撰写说明与示例/`。



## 示例与正式文档

示例用来对齐章节和粒度，正式文档另写。类名、方法、目录以当时仓库为准；代码变了就改正式文档。