如何正確記錄方法參數應該是實現某個接口的類名？

Question

我正在使用PHPDoc。 我有一個接受字符串參數的方法。 該字符串應該是實現某個接口的類的名稱，比如IMyInterface 。

我應該這樣做：

/**
 * @param string $class_name
 */
public function myMethod($class_name) {}

要么

/**
 * @param IMyInterface $class_name
 */
public function myMethod($class_name) {}

我猜測，因為類和接口在PHP中不是第一類，所以它可能是后者。 但兩種選擇似乎都有問題。

Answer 1

我使用ApiGen作為我做了一段時間的項目，我發現最好使用類名，因為它在文檔中創建鏈接到這些特定類的頁面。 我沒有使用PHPDoc，但也許它具有類似的功能，使您的文檔更容易訪問。

/**
* Constructor function.
*
* Creates a new user object with data provided.
*
* @return void
* @param mixed An array or object of user information to be read in.
* @param Permissions An instance of a Permissions object to associate with the user.
*/
public function __construct($data,$perms) {
    ...
}

Answer 2

在您的用例中，“string”是正確的，因為您正在告訴讀者確切傳遞的數據類型。如果用戶實際嘗試傳遞IMyInterface實現的具體類實例，您的代碼無疑會窒息。

如果您的方法僅構建為接受表示可用接口列表的特定字符串列表，那么我建議在方法的長描述中直接說明，而不是在一個參數的描述中。 我還會利用@see標簽提供指向此方法構建的所有接口的文檔的鏈接。 這樣，你的@param標簽真正告訴讀者“伙計，我必須有一個字符串”，你的方法描述解釋了該方法將如何獲取該字符串並將其與定義的接口相關聯，並且@see標簽將幫助讀者跳轉直接到任何/所有接口本身。

關於IDE自動完成，一些IDE可以在方法代碼中解釋“/ ** @var IMyInterface $ localMethodVar * /”，然后在$ localMethodVar上提供自動完成，就像它是IMyInterface的已定義實例一樣。