README

使用 Markdown 的 API 文档生成器

类似于 Natural Docs，但使用 100% 的 Markdown。

此项目旨在为支持文档块注释语法的任何语言编写文档。这是一个文档块的样子

/**
 * I am a doc block
 */

如何安装

通过 composer 安装很容易

composer require gears/doc:* --dev

或者您可能希望将命令全局安装到您的系统上

composer global require gears/doc:*

运行 gearsdoc 命令

安装完成后，您只需按照如下方式运行命令

/location/to/gearsdoc \
    --input="/the/path/to/your/source/code" \
    --output="/the/path/to/where/you/want/the/generated/docs/to/go"

还有很多其他选项，您可以在终端中使用 --help 选项。或者查看：方法：configure

为 gearsdoc 编写文档块

在基本层面上，要编写 gearsdoc 可以解析和理解文档块，您只需在文档块内使用 Markdown 语法即可。

注意事项

请确保您的文档块间距正确，例如以下是一个错误的文档块

/**
 *foo
 */

而以下是一个正确的文档块

/**
 * foo
 */

除此之外，没有其他硬性要求。

然而，要使用 gearsdoc 制作有效的良好文档，还有一些您需要了解的事情

标题

文档块中的第一个 <h1> 元素被认为是该文档块的标题。显然，如果文档块不包含 <h1> 元素，则我们不设置标题属性。

以下是一个包含标题的文档块

/**
 * I AM THE DOC BLOCK TITLE
 * ========================
 * this is just normal text
 */

以下是它的样子

我是这个文档块的标题

这只是普通文本

上下文

上下文是一个我们应用于生成的每个 bootstrap 面板的 CSS 类。上下文由标题确定，因此如果没有标题，则没有上下文。

默认情况下，gearsdoc 将为您设置一些上下文。如果您想添加自己的上下文，请参阅：属性：blockContexts。

以下是一个具有 Class 上下文的文档块

/**
 * Class: Baz
 * ==========
 */

以下是生成的 bootstrap 面板

类：Baz

签名

文档块之后的下一行是我们所说的签名。它通常是定义类、函数、方法或属性的代码。但它可以是任何东西。如果该行是空的，则该文档块将没有与之关联的签名。

这里是一个带有签名的文档块

/**
 * I AM THE DOC BLOCK TITLE
 * ========================
 * this is just normal text
 */
$foo = 'bar';

以下是它的样子

我就是文档块标题

$foo = 'bar';

这只是普通文本

内部链接

我非常满意这个功能。在文档块中链接到代码的各个部分非常有价值。例如，能够链接到消耗类属性的精确代码行... 无价之宝 :)

基本上有3种类型的内部链接

• 一个引用文档块标题的链接。
• 一个引用文档块签名的链接。
• 一个引用特定代码行的链接。

让我们来看一些例子

/**
 * [Method: Foo](#)
 * [private function Foo()](#)
 * [$this->foo = 'bar';](#)
 */

井号（#）表示我们将找到引用的文件。如果引用在链接相同的文件中，则只需保持井号不变。

注意：这个页面中有几个工作示例，看看你是否能找到它们。

由Brad Jones开发 - brad@bjc.id.au