### 你的第一份注釋集
#### 概述
本教程的目標是以書面形式向您介紹，并隨后使用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`的更多信息，請參閱指南。
