PHPDoc

PHPDoc 是註解 PHP 程式碼的非正式標準。它有許多不同的標記可以使用。完整的標記列表和範例可以查看 PHPDoc 指南。

底下是撰寫類別方法時的一種寫法:

<?php
/**
 * @author A Name <a.name@example.com>
 * @link http://www.phpdoc.org/docs/latest/index.html
 * @package helper
 */
class DateTimeHelper
{
    /**
     * @param mixed $anything Anything that we can convert to a \DateTime object
     *
     * @return \DateTime
     * @throws \InvalidArgumentException
     */
    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');
    }
}

這個類別說明首先使用 @author 標記，它是用來說明程式碼的作者，在多位開發者的情況下，可以同時列出好幾位。其次使用 @link 標記，它提供連一個網站連結，連結到進一步說明程式碼的網站。第三個標記使用了 @package，用來分類組織程式碼。

在這個類別中，第一個方法的 @param 標記，說明類型、名稱和傳入方法的參數。此外，@return 和 @throws 標記說明回傳類型以及可能會丟出的例外。

第二、第三個方法非常類似，和第一個方法一樣使用一個 @param 標記。第二、和第三個方法之間關鍵差別在註解區塊使用／排除 @return 標記。「@return void」標記明確告訴我們沒有回傳值，而過去省略「@return void」宣告也具有相同效果（沒有回傳任何東西）。