文档编写规范事项

文档风格

为了保障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-cnen
  • 模块 通常为相似功能的集合,或某个较为复杂的组件,新增一个模块应当谨慎
  • 章节 应当强调阅读顺序,从上到下渐进,非模块的章节可以长一些,相反模块的章节不应当过长

关键词风格

文档系统会对 .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. :::
  4. ::: warning
  5. 注意EasySwooleTemp目录不在虚拟机与宿主机共享目录下,否则会导致没有权限创建UnixSocket链接
  6. :::

效果如下:

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

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

章节案例

组件库基本结构

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

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

非组件库案例

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

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

版本痕迹

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

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

效果如下:

3.3.4新增

3.3.4新增