文档编写规范事项

文档风格

为了保障EasySwoole文档的风格基本统一，方便使用者阅读，请使用下面提供的示例风格编写文档内容。

多版本

每个章节文档默认显示最新版本对应的文档。如果组件错在多个版本，或者需要特殊说明。则请在对应章节文档开头处写上对应的版本连接。 效果如：说明2或者如说明2

  1. 风格1：
  2. [说明2](/Update/doc2.md)
  3. 风格2：
  4. <layerOpen href="/Update/doc2.md">说明2</layerOpen>

层级风格

EasySwoole 文档采用三级目录风格，语言->模块->章节 的形式进行组织内容，如某内容并不具体属于某模块，可以省略，具体组织方式如下：

  1. └── 语言
  2.     ├── 模块-1
  3.     │   └── 章节.md
  4.     ├── 模块-2
  5.     └── 章节.md

分层原则

  • 语言 毫无争议，目前仅支持zh-cn和en
  • 模块 通常为相似功能的集合，或某个较为复杂的组件，新增一个模块应当谨慎
  • 章节 应当强调阅读顺序，从上到下渐进，非模块的章节可以长一些，相反模块的章节不应当过长

关键词风格

文档系统会对 .md 格式的特定语法进行美化，为了方便大家统一风格，请使用以下语法进行关键词修饰。

希望用户在终端执行命令

如果希望用户在终端执行某命令，可以使用 引用 语法。

  1. > composer require easyswoole/easyswoole=3.4.x

效果如下：

composer require easyswoole/easyswoole=3.4.x

如果希望用户在特定的地方执行命令，最好使用 重点 注释说明

  1. *请在终端执行以下命令*
  2. > composer require easyswoole/easyswoole=3.4.x

效果如下：

请在终端执行以下命令

composer require easyswoole/easyswoole=3.4.x

高亮关键名词

如果希望在描述中高亮某些名词，可以使用 反引号 进行修饰

  1. 强大的 `TCP/UDP Server` 框架，`多线程`，`EventLoop`，`事件驱动`，`异步`，`Worker进程组`，`Task异步任务`，`毫秒定时器`，`SSL/TLS隧道加密`

效果如下：

强大的 TCP/UDP Server 框架，多线程，EventLoop，事件驱动，异步，Worker进程组，Task异步任务，毫秒定时器，SSL/TLS隧道加密

描述函数或者 function

描述函数和 function 必须简述其作用和输入输出参数，使用 代码块 指令最方便

  1. ```php
  2. DbManager::getInstance()->invoke(callable function(MysqlClient $client));

希望用户注意或警告用户

如果希望提醒用户或者警告用户，可以使用扩展语法[^非md语法] tip warning 进行描述

  1. ::: tip
  2. 旧版本的invoke没有return值，请更新orm版本。
  3. :::
  5. ::: warning  
  6.     注意EasySwoole的Temp目录不在虚拟机与宿主机共享目录下，否则会导致没有权限创建UnixSocket链接
  7. :::

效果如下：

旧版本的invoke没有return值，请更新orm版本。

注意EasySwoole的Temp目录不在虚拟机与宿主机共享目录下，否则会导致没有权限创建UnixSocket链接

章节案例

组件库基本结构

组件库的章节主要围绕如何让用户快速上手组件，和如果遇到问题如何解决构成的；优秀的文档应该是站在用户的角度进行编写的，提供可运行的代码片段非常重要。

  1. # 组件名称
  3. 在章节开头描述组件的作用和用途，以及依赖的其他组件或者注意事项；以及组件主要是用来做什么的。
  5. ## 组件要求
  7. 最好在这里说明组件要求，防止用户在安装时遭遇失败。
  9. - php >= 7.1
  10. - swoole >= 4.4
  12. ## 安装方法
  14. > composer require 组件名称
  16. ## 仓库地址
  18. 在这里给出GitHub的仓库地址 使用[仓库名称](https://github.com/easy-swoole) 来创建一个超链接
  20. ## 基本使用
  22. 在这里描述组件的常用方法，以及用来做什么，具体怎么使用；给出代码。
  24. ## 进阶使用
  26. 在这里描述组件的进阶使用方法，比如可以用作其他相关业务，给出示例。
  28. ## 相关仓库
  30. 在这里给出组件的demo仓库，或基于此组件的开源项目。

非组件库案例

非组件案例一般是指常用的核心功能，或者是某个经典案例示例。

  1. # 功能名称
  3. ## 功能介绍
  5. 在这里介绍功能的主要用途，和通常适用于什么场景。
  7. ## 相关Class位置
  9. 在这里给出Class的Github地址，或是完整的`namespace`
  11. - HttpController
  12.     - [GitHub](https://github.com/easy-swoole/http/blob/master/src/AbstractInterface/Controller.php)
  13.     - `namespace`: `EasySwoole\Http\AbstractInterface`
  15. ## 核心方法
  17. 在这里给出核心或常用方法的原型；
  19. ## 注意事项
  21. 在这里给出常见的注意事项

版本痕迹

如果某个方法是特定版本增加，应当使用 重点 或 tip 语法进行描述。

  1. *3.3.4新增*
  3. ::: tip
  4. 3.3.4新增
  5. :::

效果如下：

3.3.4新增

3.3.4新增