文檔撰寫

PHPDoc

PHPDoc 是注釋 PHP 代碼的非正式標(biāo)準(zhǔn)。它有許多不同的標(biāo)記可以使用。完整的標(biāo)記列表和范例可以查看 PHPDoc 指南。

如下是撰寫類方法時的一種寫法：

{% highlight php %}
<?php
/**
 * @author A Name <a.name@example.com>
 * @link http://www.phpdoc.org/docs/latest/index.html
 */
class DateTimeHelper
{
    /**
     * @param mixed $anything Anything that we can convert to a \DateTime object
     *
     * @throws \InvalidArgumentException
     *
     * @return \DateTime
     */
    public function dateTimeFromAnything($anything)
    {
        $type = gettype($anything);

        switch ($type) {
            // Some code that tries to return a \DateTime object
        }

        throw new \InvalidArgumentException(
            "Failed Converting param of type '{$type}' to DateTime object"
        );
    }

    /**
     * @param mixed $date Anything that we can convert to a \DateTime object
     *
     * @return void
     */
    public function printISO8601Date($date)
    {
        echo $this->dateTimeFromAnything($date)->format('c');
    }

    /**
     * @param mixed $date Anything that we can convert to a \DateTime object
     */
    public function printRFC2822Date($date)
    {
        echo $this->dateTimeFromAnything($date)->format('r');
    }
}
{% endhighlight %}

這個類的說明使用了 @author 和 @link標(biāo)記， @author 標(biāo)記是用來說明代碼的作者，在多位開發(fā)者的情況下，可以同時列出好幾位。其次 @link 標(biāo)記用來提供網(wǎng)站鏈接，進(jìn)一步說明代碼和網(wǎng)站之間的關(guān)系。

在這個類中，第一個方法的 @param 標(biāo)記，說明類型、名字和傳入方法的參數(shù)。此外，@return 和 @throws 標(biāo)記說明返回類型以及可能拋出的異常。

第二、第三個方法非常類似，和第一個方法一樣使用一個 @param 標(biāo)記。第二、和第三個方法之間關(guān)鍵差別在注釋區(qū)塊使用／排除 @return 標(biāo)記。@return void 標(biāo)記明確告訴我們沒有返回值，而過去省略 @return void 聲明也具有相同效果（沒有返回任何值）。