如何在重載方法中使用phpDoc？

Question

比方說，我有一個名爲顏色一個PHP類，它的構造函數接受各種PARAMS。

// hex color 
$myColor = new Color('#FF008C'); 

// rgb channels 
$myColor = new Color(253,15,82); 

// array of rgb channels 
$myColor = new Color(array(253,15,82)); 

// X11 color name 
$myColor = new Color('lightGreen'); 

我應該如何使用PHPDoc的用於構造和其他方法像這樣創建API文檔？

如何使用PHPDoc的重載的方法呢？

class Color { 

    /** 
    * Constructor 
    * what should be here? 
    */ 
    public function __construct() { 
     /* CODE */ 
    } 

} 

Answer 1

因爲您允許可變長度參數有兩種方法我會這樣做。

我會簡單地列出了允許的參數是參數。

/** 
* @param mixed $arg1 ... description 
* @param mixed $arg2 ... description 
* @param mixed $arg3 ... description 
*/ 
public function __construct() {} 

或者我會簡單地提供一些例子的解釋。

/** 
* Explanation of different expected argument combinations. 
*/ 
public function __construct() {} 

另一種替代方法中，由於僅其中一個例子具有多於一個參數，是簡單地定義在方法簽名使得最後2個可選的參數。就像這樣：

/** 
* @param mixed $arg1 ... 
* @param int $arg2 ... 
* @param int $arg3 ... 
*/ 
public function __construct($arg1, $arg2 = null, $arg3 = null) {} 

Answer 2

我所知，沒有優雅的方式與PHPDoc的做到這一點。 phpDoc評論/ api格式基於Javadoc格式。 Javadoc沒有一個功能來支持這個功能，因爲在java中，如果你想讓一個方法擁有可變數量的參數，你可以重新聲明每個變體的方法原型。

public double foo() { 
} 

public double foo(double my_param) {   
} 

所以，我的表現的偏好是像做

/** 
* My General description 
* 
* Here explain what each argument combination can do 
* @param mixed $arg1 can be array, string, hex as string, or int 
* @param int $arg2 if arg1 is int, then this is etc, otherwise optional 
* @param int $arg3 if ar1 is int, then this is etc, otherwise optional 
*/ 

但這可能與各種自動文檔工具發揮好。

的根據霍伊爾的方式來實現這一點可以在phpDoc site找到。

Answer 3

只是我的觀點，但你不應該有多個構造函數 - 你的構造函數將充滿if/else-ladders，這真的不是一個好主意，特別是對於輕量級的東西一種顏色的表示。

我強烈建議你去嘗試這樣的，而不是什麼：現在

class Color 
{ 
    protected function __construct($r, $g, $b) 
    { ... } 

    public static function fromHex($hex) { 
     return new Color(...); 
    } 

    public static function fromRGB($r, $g, $b) { ... } 

    public static function fromArray(array $rgb) { ... } 

    ... 
} 

，消費者代碼，而不是有些神祕和曖昧的構造函數調用像這樣：

$a = new Color(0,0,0); 
$b = new Color('#000000'); 

相反，你可以有更清晰和語義化的消費者代碼，如下所示：

$a = Color::fromRGB(0,0,0); 
$b = Color::fromHex('#000000'); 

這對閱讀消費者代碼的人來說可能更有意義，它消除了讓模糊構造函數工作所需的邏輯，並且作爲獎勵（如果您使用的是諸如PhpStorm之類的IDE），您可以讓所有檢查通過。如果您正在運行文檔生成器，則還可以確保所有選項都單獨記錄，而不是集中在一個口頭描述中。我宣佈構造protected

注意 - 這是個人喜好，但如果我要擁有多個靜態工廠的方法，我更願意看到這些消費者代碼統一使用，而不是有時看到Color::fromRGB(...)等次new Color(...)。

Answer 4

我認爲這是更好地使用@method標註爲類/接口，其中聲明重載方法。這個問題對我也很有趣。

/** 
    * @method void setValue(int $value) 
    * @method void setValue(string $value) 
    * @method void setValue(string $value, int $startFrom) 
    */ 
class Example 
{ 
    public function setValue($arg1, $arg2) 
    { 
     // ... 
    } 
} 

見http://phpdoc.org/docs/latest/references/phpdoc/tags/method.html