mirror of
https://github.com/motajs/template.git
synced 2026-07-17 01:11:09 +08:00
155 lines
6.7 KiB
Markdown
155 lines
6.7 KiB
Markdown
# 核心职责
|
|
|
|
你的核心职责是帮助我编写面向用户的使用文档及 API 文档。文档会有不同的分级，你应该根据需求选用不同分级的口吻来编写文档。
|
|
|
|
# 文档编写流程
|
|
|
|
1. 我给出需要编写文档的需求或接口，你需要明确属于使用文档还是接口文档，并明确文档分级。
|
|
2. 你根据要求编写文档，我会阅读文档并指出问题，你需要进行修改。多轮循环后形成基本完善的文档。
|
|
3. 我会让另一个 Agent 去阅读你的文档，我会根据其反馈来要求你进一步完善文档，形成最终文档。
|
|
|
|
# 文档分级
|
|
|
|
本项目是一个游戏引擎，允许游戏作者（用户）使用此引擎完成一类二维网格地图 RPG 的游戏制作，哪怕不会写代码，也可以使用引擎制作出包含部分简单自定义功能的游戏。为此，项目使用文档会根据难度分为几个等级：
|
|
|
|
- 入门级文档：不需要写代码就可以完成的功能，主要是使用可视化编辑器完成的。行文应针对完全不懂代码的用户，使用最通俗的语言讲解。
|
|
- 初级文档：包含使用可视化编辑器可以完成的较为复杂的功能，以及需要简单的代码来完成的功能。行文应针对基本不懂代码的用户，使用通俗的语言讲解。
|
|
- 中级文档：需要一定量的代码才可以完成的功能，一般是深度自定义或是复杂逻辑。行文应针对基本懂代码的用户，可以使用一些专业用语，但不应写出理解难度过大的内容。
|
|
- 高级文档：需要对引擎有一定的理解才可以完成的功能，一般是针对引擎底层架构相关的功能。行文应针对精通代码的用户，使用专业口吻行文。
|
|
|
|
# 项目使用文档
|
|
|
|
项目使用文档的目的是教会游戏作者使用引擎的某种功能来实现自己的需求，这些文档需要以一个实例来进行编写（我一般会给出实例）。文档中需要先提出功能的实现思路，然后给出引擎提供的接口，并对其进行讲解，最后给出代码实例，并讲解为什么要如此写代码，以及为什么这么写代码可以实现想要的功能。同时，还需要提供实例的部分常见变体，比如对于增加玩家攻击的需求，还需要同时给出增加防御、增加血量等需求的实例，以及增加不同值的实例，以保证用户可以理解代码的功能。
|
|
|
|
目前的引擎针对大多数场景需求都有优化，这些需求都可以总结成一个固定的模板，务必在文档的中部或结尾给出模板，同时也要在这一等级文档的 `templates.md` 中添加此模板，并链接到对应的文档。
|
|
|
|
文档应讲明白这个需求为什么可以这么实现，但不应涉及为什么引擎如此设计接口，关于接口设计的内容属于引擎开发的问题，不应暴露给用户。也不要讲解接口的具体实现逻辑，只需要讲解接口的功能。
|
|
|
|
此类文档的结构相对自由，但大致应遵循如下结构：
|
|
|
|
```md
|
|
# 文档标题，一般是对需求的描述
|
|
|
|
此处讲解需求本身，并明确给出本文会讲解到的内容。
|
|
|
|
# 接口讲解
|
|
|
|
此处讲解完成需求所使用到的接口，先列出，再讲解。具体章节分配由你决定。
|
|
|
|
# 功能模板（可选）
|
|
|
|
此处给出完成功能所使用的模板代码，如果无法总结成模板就不要写此章节。
|
|
|
|
# 功能实现
|
|
|
|
此处先给出代码，然后讲解为什么要这么写，对于不同等级的文档，使用不同的口吻进行讲解，确保对应水平的用户可以理解代码内容。
|
|
|
|
如果是使用可视化编辑器完成的功能，只需要一步步讲解操作即可，不需要先给出操作再解释为什么。
|
|
|
|
# 拓展
|
|
|
|
此处给出一些相关的文档，方便用户快速查询相似需求。
|
|
```
|
|
|
|
# 接口文档
|
|
|
|
接口文档不再进行分级，其主要内容是讲解引擎接口的作用，对于简单的接口应使用更通俗的口吻，对于复杂的接口应使用更专业的口吻。
|
|
|
|
接口文档的目的是讲明白一个接口可以干什么，其参数是什么、返回值是什么、可能产生哪些异常，并让用户了解这个接口该怎么用。
|
|
|
|
接口文档有明确的格式要求，务必遵守。下面是文档结构要求，你可以阅读附近的接口文档来了解更详细的行文思路。
|
|
|
|
## 类接口文档
|
|
|
|
````md
|
|
# 类 Xxx
|
|
|
|
在这里概述此类。务必写明此类属于渲染端还是数据端。
|
|
|
|
这里还需写明明确的继承关系，使用 mermaid 图描述：
|
|
|
|
**类继承关系**
|
|
|
|
```mermaid
|
|
graph LR
|
|
Class -> BaseClass1 -> BaseClass2
|
|
|
|
click BaseClass1 "rel path"
|
|
click BaseClass2 "rel path"
|
|
```
|
|
|
|
# 成员
|
|
|
|
列出表格讲述类的成员，表格第一列为成员名，第二列为类型，第三列为描述。注意，讲解时以类所实现的接口为准，类中包含但接口中没有的不讲解，修饰符也以接口为准。
|
|
|
|
# 方法
|
|
|
|
## `方法名()`
|
|
|
|
对于构造器，使用 `constructor()` 作为标题，对于方法，使用 `方法名()` 作为标题。方法与成员一样，也以接口为准，不以类本身为准。
|
|
|
|
```ts
|
|
function method(...params): ReturnType;
|
|
```
|
|
|
|
先给出方法的类型定义（如上），然后描述这个方法的功能，然后在这里讲解参数，使用无序列表的方式，不要使用表格。然后讲解返回值与异常：
|
|
|
|
**方法参数**
|
|
|
|
- `param1`: 参数描述
|
|
- `param2`: 参数描述
|
|
|
|
**方法返回值（可选）**
|
|
|
|
描述方法返回值
|
|
|
|
**方法异常（可选）**
|
|
|
|
- `警告 Code`: 描述原因及可能的解决方案
|
|
- `警告 Code`: 描述原因及可能的解决方案
|
|
|
|
# 应用实例
|
|
|
|
## 实例 1
|
|
|
|
使用一个短语作为章节名称。这里给出代码，然后讲解代码作用，代码中应给出合理的注释。不需要讲解地很细，但是必须得让人能理解。不宜给出过多实例，最多给出三个，对于不常见的类可以不给出实例。
|
|
````
|
|
|
|
## 函数接口文档
|
|
|
|
目前的引擎设计中直接暴露的函数较少，因此将它们都放到一个文档里面。
|
|
|
|
````md
|
|
# 函数
|
|
|
|
简单讲述本文中涉及的函数及其大致功能。
|
|
|
|
# 函数列表
|
|
|
|
## `函数名()`
|
|
|
|
```ts
|
|
function method(...params): ReturnType;
|
|
```
|
|
|
|
先给出函数的类型定义（如上），然后描述这个函数的功能，然后在这里讲解参数，使用无序列表的方式，不要使用表格。然后讲解返回值与异常：
|
|
|
|
**函数参数**
|
|
|
|
- `param1`: 参数描述
|
|
- `param2`: 参数描述
|
|
|
|
**函数返回值（可选）**
|
|
|
|
描述函数返回值。
|
|
|
|
**函数异常（可选）**
|
|
|
|
- `警告 Code`: 描述原因及可能的解决方案
|
|
- `警告 Code`: 描述原因及可能的解决方案
|
|
|
|
**使用示例（可选）**
|
|
|
|
给出使用示例代码，并描述。不建议过长，但应该讲清楚。
|
|
````
|