Skip to content

Latest commit

 

History

History
191 lines (113 loc) · 4.64 KB

README.md

File metadata and controls

191 lines (113 loc) · 4.64 KB
Raw

文档编写规范事项

文档风格

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

层级风格

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

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

分层原则

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

关键词风格

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

希望用户在终端执行命令

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

> composer require easyswoole/easyswoole=3.4.x

效果如下：

composer require easyswoole/easyswoole=3.4.x

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

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

效果如下：

请在终端执行以下命令

composer require easyswoole/easyswoole=3.4.x

高亮关键名词

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

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

效果如下：

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

描述函数或者 function

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

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

希望用户注意或警告用户

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

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

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

效果如下：

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

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

章节案例

组件库基本结构

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

# 组件名称

在章节开头描述组件的作用和用途，以及依赖的其他组件或者注意事项；以及组件主要是用来做什么的。

## 组件要求

最好在这里说明组件要求，防止用户在安装时遭遇失败。

- php >= 7.1
- swoole >= 4.4

## 安装方法

> composer require 组件名称

## 仓库地址

在这里给出GitHub的仓库地址 使用[仓库名称](https://github.com/easy-swoole) 来创建一个超链接

## 基本使用

在这里描述组件的常用方法，以及用来做什么，具体怎么使用；给出代码。


## 进阶使用

在这里描述组件的进阶使用方法，比如可以用作其他相关业务，给出示例。


## 相关仓库

在这里给出组件的demo仓库，或基于此组件的开源项目。

非组件库案例

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

# 功能名称

## 功能介绍

在这里介绍功能的主要用途，和通常适用于什么场景。

## 相关Class位置

在这里给出Class的Github地址，或是完整的`namespace`

- HttpController
    - [GitHub](https://github.com/easy-swoole/http/blob/master/src/AbstractInterface/Controller.php)
    - `namespace`: `EasySwoole\Http\AbstractInterface`

## 核心方法

在这里给出核心或常用方法的原型；

## 注意事项

在这里给出常见的注意事项

版本痕迹

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

*3.3.4新增*

::: tip
3.3.4新增
:::

效果如下：

3.3.4新增

::: tip 3.3.4新增 :::