3.4 KiB
3.4 KiB
撰写总则
目录
文档分三类
| 文档 | 位置 | 正文 |
|---|---|---|
| 项目架构 | doc/项目架构.md，全库一篇 |
目录结构（到 features/[feature]）、模块定义、功能模块之间的业务数据流 |
| 基础应用 | doc/基础应用/，src/app 下，一个目录一篇 |
功能定义、使用示例、该应用内部的数据流与时序 |
| 功能模块 | doc/功能模块/，src/features 下一个目录一组 |
模块内目录、功能定义、核心业务层与核心模型、核心业务时序图 |
src/app 下的每个目录是一个基础应用。src/features 下的每个目录是一个功能模块。
章节的写法分别见：
每篇文档都写目录
标题下第一段是目录，标题为「目录」。条目与正文标题一致，并链到对应标题。拆出去的业务文档写进父文档目录，链到文件。
撰写说明、示例、正式文档都要有目录。
图中只用项目词条
Mermaid 的节点、参与者、箭头文字只用仓库里的目录名、类名、方法名、字段名。中文说明写在图外的正文里。
图只画本层
项目架构只画 home、security、project、editor 之间的业务数据。不画 session、network、db、routes 这些基础应用，也不画时序。
基础应用只画该目录内部的类和函数。不画功能模块的调用链，也不把其他基础应用的内部步骤画进来。调用方可以出现在使用示例的代码里。时序图已经能说明这条行为时，不再画数据流图。
功能模块的时序写在功能模块文档。那里不展开基础应用内部步骤。
功能模块何时拆开
一条主业务时，时序图写在该模块主文档里。
同一模块有多条要分开讲述的事件业务时，为每条业务另写一篇，放在该模块目录下。主文档保留目录结构、功能定义、核心业务层与核心模型，并用目录链到各业务文档。编辑器的打开、绘制、撤销与重做按这个方式拆开。
方法定义写在主文档的核心业务层。业务文档写该业务的定义和时序图，并点名用到的方法。
文件名
- 基础应用：
中文名(目录名).md，例如会话(session).md。 - 功能模块主文档：
模块名(目录名).md，例如编辑器模块(editor).md。 - 拆出的业务文档：放在同一模块目录，用业务名作文件名，例如
绘制.md。 - 说明与示例只放在
doc/文档撰写说明与示例/。
示例与正式文档
示例用来对齐章节和粒度，正式文档另写。类名、方法、目录以当时仓库为准；代码变了就改正式文档。