### 你的第一份注释集
#### 概述
本教程的目标是以书面形式向您介绍，并随后使用phpDocumentor生成有效的文档。
#### 写一个文档块
`DocBlock`是源代码中的一段内联文档，用于告诉您，其它的`类`，`方法`或其他`结构元素`的功能。
##### 哪些元素可以记录？
讨论`DocBlock`之前，我们首先看一下您可以用`DocBlock`来记录的内容。
`phpDocumentor`遵循`PHPDoc`的定义，并主要用于识别以下结构元素：
* Function（函数）
* Constant（常量）
* Class（类）
* Interface（接口）
* Trait（Trait）
* Class constant（类常量）
* Property（属性）
* Method（方法）
除上述外，PHPDoc标准还支持DocBlocks 为文件以及`include / require`语句进行注释，即使PHP本身并不知道这个概念。
这里面的每一个元素都可以有一个与之关联的`DocBlock`，它直接位于这些元素的前面。`DocBlock`和元素定义的开始之间应该没有代码或其它注释。
##### DocBlock的外观如何？
`DocBlocks`总是被包含在一个名为 `DocComment`的注释类型中，该注释类型始于`/**`并以`*/`结束。开始和结束语句之间的每一行都应以星号（`*`）开头。每个 `DocBlock`先于一个结构元素，而 `DocBlock`的所有内容都应用于该关联元素。
例如:
~~~
<?php
/**
* This is a DocBlock.
*/
function associatedFunction()
{
}
~~~
> 注意 文件级别的DocBlocks
很多时候项目会想要为整个文件而不是单个元素记录许可证或功能。这可以通过将`DocBlock`作为文件中的第一个元素来完成。需要注意的是，每当另一个结构元素直接跟随DocBlock时，它不再被识别为文件级别的DocBlock，而是属于后续元素。
以下DocBlock是一个文件级别的DocBlock：
~~~
<?php
/**
* I belong to a file
*/
/**
* I belong to a class
*/
class Def
{
}
~~~
但是在下面的例子中，DocBlock属于这个类：
~~~
<?php
/**
* I belong to a class
*/
class Def
{
}
~~~
DocBlocks分为以下三部分。这些部分中的每一部分都是可选的，除了 没有概要的描述属性可能不存在。
###### 概要
有时称为简短描述，简要介绍关联元素的功能。摘要以这些情况之一结束：
一个点跟随一个换行符，或遇到两个后续换行符。
###### 描述
有时称为长描述，可以提供更多信息。附加信息的例子是函数算法的描述，用例或描述类如何适应整个应用程序的体系结构。描述在遇到第一个标记或`DocBlock`关闭时结束。
###### 标签和注释
这些提供了一种简洁而统一地提供关于相关元素的元信息的方式。例如，这可以描述方法或函数返回的信息类型。每个标签前面都有一个符号（@），并以新行开始。
#### 示例
一个DocBlock看起来像这样
~~~
<?php
/**
* A summary informing the user what the associated element does.
*
* A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
* and to provide some background information or textual references.
*
* @param string $myArgument With a *description* of this argument, these may also
* span multiple lines.
*
* @return void
*/
function myFunction($myArgument)
{
}
~~~
我们一行一行地讨论这个例子，讨论哪个是哪个，
* 第2行
从`/**`开始，显示一个DocBlock。
* 第3行
带有一个摘要的例子。通常是一行，但也可能会覆盖多行，只要未达到前一章中定义的摘要末尾。
* 第5行和6行
显示一个描述的例子，它可能跨越多行，并且可以使用Markdown标记语言进行格式化 。使用Markdown，您可以使文本变为粗体，斜体，添加编号列表，甚至提供代码示例。
* 第8行和第11行
表明您可以在DocBlocks中包含标签以提供有关后续元素的附加信息。在这个例子中，我们声明参数`$myArgument`是`string`类型的，并且描述了这个参数代表什么，我们还声明了这个方法的返回值是`void`，这意味着没有返回值。
* 第12行
显示闭幕声明`*/`，这与多行注释（）相同。`/* .. */`
如果您想了解更多关于DocBlocks为您做些什么，请参阅`Inside DocBlocks`一章以获取更深入的信息。
#### 运行phpDocumentor
在你安装完`phpDocumentor`之后，你可以使用`phpdoc`命令生成相应的文档。
在本文中，我们预计phpdoc命令可用; 因此，无论何时我们要求您运行命令，它都将采用以下形式：
~~~
$ phpdoc
~~~
暗示 当你通过编辑器或手动安装版本时，应该调用phpDocumentor安装文件夹中的phpdoc脚本bin。
在Linux / MacOSX下，这将是：
~~~
$ [PHPDOC_FOLDER] / bin / phpdoc
~~~
在Windows下，这将是：
~~~
$ [PHPDOC_FOLDER] \ bin \ phpdoc.bat
~~~
`phpDocumentor`的基本用法是使用命令行选项（`-d`对于目录，`-f`对于文件）提供输入位置，并告诉它将文档输出到您喜欢的文件夹（`-t`）中。
例如：
~~~
$ phpdoc -d ./src -t ./docs/api
~~~
上面的例子是扫描`src`目录及其子目录中的所有文件，执行分析并生成包含文件夹中文档的网站`docs/api`。如果你想要，你甚至可以省略`-t` 选项，在这种情况下，输出将被写入到一个名为的子文件夹中`output`。
> 提示 `phpDocumentor`具有几个[模板](https://phpdoc.org/templates)，您可以使用它更改文档的外观。有关如何在模板之间切换的更多信息，请参阅[`更改外观和感觉`](https://docs.phpdoc.org/getting-started/changing-the-look-and-feel.html)一章。
`phpDocumentor`有很多选项，您可以在[`配置文件`](https://docs.phpdoc.org/references/configuration.html)中将它们全部定义并包含在您的项目中，但这不在本教程的范围之内。如果你想知道更多关于[运行`phpDocumentor`](https://docs.phpdoc.org/guides/running-phpdocumentor.html)的信息; 有关运行`phpDocumentor`的更多信息，请参阅指南。
