PHP 関数のドキュメントガイドライン

PHP 関数ドキュメントの仕様では、必須フィールドに関数名、パラメーター (デフォルト パラメーターを含む)、戻り値、および例外を含めることが必要です。オプションのフィールドには、説明、エイリアス、互換性、非推奨、および削除バージョンが含まれます。記述ルールでは、明確で簡潔な言語を重視し、DocBlock コメント形式を使用し、関数の使用法と入力ヒントを示す実践例を示します。

#PHP 関数ドキュメントの記述仕様

明確で一貫性のある関数ドキュメントを作成するには、次の仕様に従ってください。

必須フィールド:

• 関数名: CamelCase で表現された関数の一意の識別子。
• Parameters: 関数によって受け入れられるパラメータのリスト。$param1、$param2 などを使用して順番に名前が付けられます。
• デフォルトパラメータ: 関数のパラメータにデフォルト値がある場合は、パラメータ名の後に =default_value を使用して指定してください。
• 戻り値: 関数によって返される値のタイプ。
• Exceptions: 関数によってスローされる可能性のある例外のリスト。
• 例: 関数の使用方法を示す 1 つ以上のコード例。

オプションのフィールド:

• 説明: 関数の機能と目的の簡単な説明。
• Alias: 関数の任意のエイリアス。
• 互換性: 関数がサポートする PHP バージョン。
• PHP バージョン以降非推奨: 関数の非推奨バージョン。
• PHP バージョンから削除されました: この関数は PHP バージョンから削除されました。

書き方のルール:

明確で簡潔な言葉を使用してください。
• 時代遅れの用語や専門用語は避けてください。
• 開発者が関数の動作を理解できるように、十分な情報を提供します。
• [DocBlock コメント形式](https://www.php.net/manual/en/ language.types.declarations.php) を使用します。

実践的なケース:

/**
 * 计算两个数的平均值。
 *
 * @param float $num1 第一个数
 * @param float $num2 第二个数
 * @return float 平均值
 */
function average(float $num1, float $num2): float
{
    return ($num1 + $num2) / 2;
}

その他のヒント:

コード スニペットを使用して関数の使用法を示す。
• 詳細情報を提供する関連関数またはクラスへのリンク。
• 可能であれば、コードの可読性を向上させるために型ヒントを提供します。
• ドキュメントを定期的に確認して、正確さと一貫性を確保してください。

以上がPHP 関数のドキュメントガイドラインの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。