Can you summarize the following document?
        
  

  文件塊是一種擴充套件了 C++ 風格的 PHP 註釋,它以 "/**" 開始,並在每一行的行首有一個 "*" 。文件塊 DocBlocks 位於被註釋區域的前面,在文件塊中,任何不以 * 開始的行將被忽略。  要註釋 "foo()",請將文件塊放在緊挨著函式宣告的前面:  下面的例子將會應用文件塊到 "define('me',2);",而不是 "function foo()":  define() 語句,函式,類,類方法,類變數,include() 語句和全域性變數都可以被文件化。see Elements of the source code that can be documented  一個文件塊通常會以如下的順序包含三個基本片段:  短介紹開始於第一行,以一個空行或一個句號(這裡是指英文句號,下同)結束。單詞中的句號(例如 example.com 或 0.1%)會被忽略。如果短介紹長度超過三行,則只有第一行有效。而長描述則以任意多行繼續,而且可以包含 用於格式化顯示的 HTML 標記。下面是一個帶有短介紹和長描述的文件塊:  另外,你還可以把所有段落放在一對 </p> 標籤中。要小心,如果第一段沒有以一個  開頭,phpDocumentor 將會假設文件塊只是像下面這樣使用簡單的雙換行符定義段落分割:  這兒是一個使用  的例子:  通過命令列選項 -j, --javadocdesc,phpDocumentor 也可以支援 JavaDoc 的文件塊格式。由於不匹配的 p 標籤不相容 XHTML 標準,我們強烈建議你儘可能避免使用這種語法。  phpDocumentor 會將長描述中所有的空白轉換為單個空格。請使用斷行定義新行,或者使用下一節中討論的 <pre> 。

  在有的解析器中,文件塊中的若干 HTML 標籤可能會被解析以顯示特定的資訊。由於並非所有的HTML標籤都是允許使用的,它們有可能被轉換為普通文字或更加視具體內容而定的表情。例如,一個 <b> 標籤可能會被轉換為 <emphasis> 。  下面是 phpDocumentor 所支援的標籤列表:  For the rare case when the text "<b>" is needed in a DocBlock, use a double delimiter as in «b». phpDocumentor will automatically translate that to the physical text "<b>".

  <code> 和 <pre> 中的內容會忽略上述列表中的任何 HTML 標籤。(當然,它們自己對應的關閉標籤除外)

  文件塊模板的目的是縮減重複的輸入。例如,如果有大量的類成員變數是私有的,我們可以使用一個文件塊模板標記它們的屬性為私有。文件塊模板就是簡單地擴充了其中的普通文件塊。  一個文件塊模板是通過它頭部的一個普通文件塊識別的。下面是一個最基本的文件塊模板:  將其標記為一個文件塊模板的文字是 "/**#@+" - 嗯,6個字元都是必須存在的。文件塊模板會一直應用到所有的可文件化的元素,直到出現模板結束標記:  注意,所有的8個字元必須呈現為 "/**#@-*/",這樣 phpDocumentor 才會將其識別為一個模板。

  頁面級的文件塊是唯一一種無法把自己放在被註釋元素之前的文件塊。因為沒有辦法將註釋放在一個檔案的前面(非文件內容的前面)。為了解決這個問題,phpDocumentor 的方式是將一個檔案中出現的符合某些條件的第一個文件塊作為頁面級文件塊。  上面的例子中有一個文件塊,而且它是檔案中出現的第一個文件塊,但它不是一個頁面級文件塊。那麼 phpDocumentor 是怎樣區分頁面級文件塊和其他文件塊的呢?簡單:  在 1.2.2 版的 phpDocumentor 中,頁面級的文件塊就是檔案中出現的第一個含有 @package 標籤的文件塊。然而,這個例子將會導致一個 WARNING 錯誤:Page-level DocBlock precedes "define almost", use another DocBlock to document the source element. 你可以通過在文件中對 define 語句新增類似下面的註釋避免這個 WARNING:  現在,頁面級文件塊屬於這個頁面,而 define 語句也有了自己的文件塊。  So, 一個文件塊僅在同時符合以下條件時,它才是一個頁面級文件塊:  一個頁面級文件塊可以含有所有的普通 phpDocumentor 標籤,以及下列標籤:  phpDocumentor 不會文件化像第一個例子中的檔案,檔案中必須有至少一個可文件化的 PHP 元素。

  Tags are single words prefixed by a "@" symbol. Tags inform parsers how to present information and modify display of documentation as well as allow the IDE to define variable types. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.  In addition, some parsers allow two addition inline tags: {@id}, used to allow direct linking to sections in a tutorial, and {@toc}, used to generate a table of contents from {@id}s in the file. Think of {@id} like an <a name="idname"> HTML tag as it serves the same function.  For more in depth discussion of PHPDoc tags, see http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html

  To understand the role of packages and how to use @package, it is important to know the logic behind packaging in PHP. The quest for structured programming led to the invention of functions, then classes, and finally packages. Traditionally, a re-usable software module was a collection of variables, constants and functions that could be used by another software package. PHP is an example of this model, as there are many extensions that consist of constants and functions like the tokenizer extension. One can think of the tokenizer extension as a package: it is a complete set of data, variables and functions that can be used in other programs. A more structured format of this model is of course objects, or classes. A class contains variables and functions. A single class packages together related functions and variables to be re-used.  phpDocumentor defines package in two ways:  These two definitions of package are exclusive. In other words, it is possible to have classes of a different package of the file that contains it.
PHPDoc 是一個 PHP 版的 Javadoc。它是一種註釋 PHP 程式碼的正式標準。它支援通過類似 phpDocumentor 這樣的外部文件生成器生成 API 文件,也可以幫助一些例如 Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之類的 整合開發環境 理解變數型別和弱型別語言中的其他歧義並提供改進的程式碼完成,型別提示和除錯功能。