PHP 高級程序設計學習筆記20140612
軟件開發中的一個重要環節就是文檔編寫。他可以幫助未來的程序維護人員和使用者理解你在開發時的思路。也便於日後重新查看代碼時不至於無從下手。文檔還有一個重要的作用，在不用了解要訪問對象的細節情況下也能很好的在對象之間進行交互。文檔的編寫有一些成熟的行業標准格式，遵守這些行業標准將有助於創建易於閱讀的代表，並使自動生成手冊成為可能。
編碼規范
編碼規范可能很多開發人員都有各自的觀點也意見，且大家不盡相同。其實只要團隊成員之間達成一致，遵循同一個標准就好。
PHP社區百花齊放，擁有大量的函數庫、框架和組件。PHP開發者通常會在自己的項目中使用若干個外部庫，因而PHP代碼遵循或盡量接近 同一個代碼風格就非常重要，可以讓開發者方便地把多個代碼庫集成在自己的項目中。框架互操作組(即PHP標准組)發布了一系列推薦風格。其中有部分是關於代碼風格的，即PSR-0，PSR-1，PSR-2和PSR-4。通常情況下，你的PHP代碼應該遵循其中一項或多項標准，從而其他開發者可以方便地閱讀和使用你的代碼。這些標准都是在前一個標准 上附加新的規則，所以使用PSR-1就同時要求遵循PSR-0，但可以不遵循PSR-2。
文檔編寫 - 注釋的類型
PHP 中常用的三種注釋方法，注釋是增加程序可讀性、可維護性的一種方法，而不是唯一方法。可讀性和可維護性主要還是在代碼命名，項目組織處提高。
//這是一個單行注釋類型 /* 這是一個多行注釋類型 第二行注釋 */ /** * * 這種形式的注釋被稱為 文檔注釋 */
第一種注釋可以說是給人看的，一般用來比較簡短的注釋。第二種，則用在需要大量注釋的代碼中。第三種注釋被稱為文檔注釋，可以被及其解釋，且能以固定的格式放到手冊中去。注釋的種類主要包括：類的注釋，屬性注釋、方法注釋、變量注釋以及關鍵算法、重要代碼實現等。所有的這些部分編織在一起，使得人們在以後的時間裡能夠准確的知道你干了什麼，為什麼這麼做。
文檔編寫 - 文法解析
從編程語言到可執行代碼的轉換過程叫做文法解析。當文法解析器遇到一個正常的注釋時，它會識別它並忽略它，並且清理掉注釋中的數據，因此一般的注釋是無法遷入元數據的。
元數據
元數據的定義是 data about data 。是一種廣泛存在的現象，在許多領域有具體的定義和應用。其被定義為：描述數據的數據，對數據及信息資源的描述性信息。PHP包含了大多數編程元素的元數據。然而，你可能需要嵌入更多的元數據，因為元數據在自動生成文檔方面非常有用。這種功能可以通過文檔注釋的解析來模擬。如果創建遵循特定格式的文檔注釋，解析器可以將注釋自動轉換稱為有意義的文檔。
PHPDoc
PHPDoc 是用於維護PHP文檔的解決方案。其為文檔注釋定一輛一種結構，允許解析器以一致的方式解析它們。有了PHPDoc就可以從嵌入文檔中創建手冊了。 和所有文檔注釋一樣，PHPDoc 要求必須以/**注釋聲明開始。PHPDoc 的特殊之處在於標簽。 標簽由@開始加上一個預定義的標示符表示。關於PHPDoc的更多信息請參考 http://www.phpdoc.org/docs/latest/index.html
PHPDoc 規范的注釋
注釋塊必須以“/**”開始，以“*/”結束。
開始注釋和結束之間的每行都以星號（*）開始。
標簽必須以 at-sign (@) 開頭在新行書寫，接著寫標
有幾個標簽支持或需要用類型來表示包含在相關元素的值的類型。這方面的一個例子是“param標記，以確定一個方法或函數參數的類型。
Here is a full listing：
string：A piece of text of an unspecified length.
int or integer：A whole number that may be either positive or negative.
float：A real, or decimal, number that may be either positive or negative.
bool or boolean：A variable that can only contain the state ‘true’ or ‘false’.
array：A collection of variables of unknown type. It is possible to specify the types of array members, see the chapter on arrays for more information.
resource：A file handler or other system resource as described in the PHP manual.
null：The value contained, or returned, is literally null. This type is not to be confused with void, which is the total absence of a variable or value (usually used with the @return tag).
callable：A function or method that can be passed by a variable, see the PHP manual for more information on callables.
下面列出PHPDoc的全部標簽：
@api @author @category @copyright @deprecated @example @filesource @global @ignore @internal @license @link @method @package @param @property @property-read @property-write @return @see @since @source @subpackage @throws @todo @uses @var @version
