php 函數(shù)文檔編寫規(guī)范隨著 php 版本更新而不斷演變，主要變化包括：php 5.x 版本采用 javadoc 格式的文檔塊。php 7.x 版本引入 phpdoc 注解語法，支持類型聲明和異常處理文檔。php 8.x 版本引入版本標(biāo)簽、返回值類型聯(lián)合和推進(jìn)器類型聲明。
PHP 函數(shù)文檔編寫規(guī)范的版本演變
PHP 函數(shù)文檔規(guī)范的變化與 PHP 版本的更新密切相關(guān)。隨著時(shí)間的推移，PHP 團(tuán)隊(duì)不斷優(yōu)化和改進(jìn)文檔編寫規(guī)則，以提高文檔的易讀性、一致性和準(zhǔn)確性。
PHP 5.x 版本
文檔區(qū)塊格式：與 JavaDoc 類似，使用 /** ... */ 作為文檔塊。
標(biāo)簽：使用 @ 開頭的標(biāo)簽注明函數(shù)信息，如 @param、@return 等。
描述：描述函數(shù)的目的和使用方法，清晰簡練。
示例：推薦使用代碼示例展示函數(shù)的用法。
PHP 7.x 版本
引入 PHPDoc：采用 PHPDoc 注解語法，擴(kuò)展了文檔規(guī)范。
類型聲明：加入類型聲明，明確函數(shù)參數(shù)和返回值類型。
異常處理文檔：增加文檔塊的 @throws 標(biāo)簽，標(biāo)記函數(shù)可能拋出的異常。
可見性標(biāo)簽：引入 @<a style="color:#f60; text-decoration:underline;" href="https://www.php.cn/zt/16380.html" target="_blank">access</a> 標(biāo)簽，標(biāo)識函數(shù)的可見性（public、protected、private）。
PHP 8.x 版本
版本標(biāo)簽：在文檔塊前面添加 @psalm-version 標(biāo)簽，指定文檔適用于哪個(gè) PHP 版本。
返回值類型聯(lián)合：允許使用類型聯(lián)合聲明返回值類型，表示函數(shù)可以返回多種類型。
推進(jìn)器類型：可以使用 yield 類型聲明返回推進(jìn)器。
實(shí)戰(zhàn)案例
以下是按照最新 PHP 8.x 規(guī)范編寫的 max() 函數(shù)文檔塊：
/**
* @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');
}
登錄后復(fù)制
這個(gè)文檔塊遵循了最新的規(guī)范，包含版本標(biāo)簽、參數(shù)類型聲明、返回值類型聯(lián)合、異常處理文檔和描述。
