php 函數文檔編寫規范隨著 php 版本更新而不斷演變，主要變化包括：php 5.x 版本采用 javadoc 格式的文檔塊。php 7.x 版本引入 phpdoc 注解語法，支持類型聲明和異常處理文檔。php 8.x 版本引入版本標簽、返回值類型聯合和推進器類型聲明。
PHP 函數文檔編寫規范的版本演變
PHP 函數文檔規范的變化與 PHP 版本的更新密切相關。隨著時間的推移，PHP 團隊不斷優化和改進文檔編寫規則，以提高文檔的易讀性、一致性和準確性。
PHP 5.x 版本
文檔區塊格式：與 JavaDoc 類似，使用 /** ... */ 作為文檔塊。
標簽：使用 @ 開頭的標簽注明函數信息，如 @param、@return 等。
描述：描述函數的目的和使用方法，清晰簡練。
示例：推薦使用代碼示例展示函數的用法。
PHP 7.x 版本
引入 PHPDoc：采用 PHPDoc 注解語法，擴展了文檔規范。
類型聲明：加入類型聲明，明確函數參數和返回值類型。
異常處理文檔：增加文檔塊的 @throws 標簽，標記函數可能拋出的異常。
可見性標簽：引入 @<a style="color:#f60; text-decoration:underline;" href="https://www.php.cn/zt/16380.html" target="_blank">access</a> 標簽，標識函數的可見性（public、protected、private）。
PHP 8.x 版本
版本標簽：在文檔塊前面添加 @psalm-version 標簽，指定文檔適用于哪個 PHP 版本。
返回值類型聯合：允許使用類型聯合聲明返回值類型，表示函數可以返回多種類型。
推進器類型：可以使用 yield 類型聲明返回推進器。
實戰案例
以下是按照最新 PHP 8.x 規范編寫的 max() 函數文檔塊：
/**
* @psalm-version 8.0
* @param array<scalar> $values Array of scalar values
* @return scalar The maximum value in the array
* @throws TypeError if any value in the array is not scalar
*/
function max(array $values): scalar
{
if (!empty($values)) {
$max = $values[0];
foreach ($values as $value) {
if ($value > $max) {
$max = $value;
}
}
return $max;
}
throw new TypeError('Array must contain at least one scalar value');
}
登錄后復制
這個文檔塊遵循了最新的規范，包含版本標簽、參數類型聲明、返回值類型聯合、異常處理文檔和描述。
