Aperçu des spécifications du document de fonction PHP
La spécification de rédaction de documents de fonction PHP nécessite que les champs requis incluent le nom de la fonction, les paramètres (y compris les paramètres par défaut), la valeur de retour et l'exception. Les champs facultatifs incluent la description, l'alias, la compatibilité, la dépréciation et la suppression des versions. L'écriture des règles met l'accent sur le langage clair et concis, utilise le format d'annotation DocBlock et démontre l'utilisation de la fonction et les invites de type à travers des exemples de cas.
Champs requis
- Nom de la fonction: un identifiant unique de la fonction, nommé à l'aide de CamelCase.
- Paramètres: la liste des paramètres acceptés par la fonction, nommé par $ param1, $ param2, etc.
- Paramètres par défaut: si les paramètres de la fonction ont des valeurs par défaut, spécifiez-les avec = default_value après le nom du paramètre.
- Valeur de retour: le type de valeur renvoyée par la fonction.
- Exception: une liste d'exceptions qu'une fonction peut lancer.
- Exemple: exemple de code utilisé par une ou plusieurs fonctions de démonstration.
Champs facultatifs
- Description: Une brève description des fonctions de fonction et des utilisations.
- Alias: tout alias pour la fonction.
- Compatibilité: la version PHP prise en charge par la fonction.
- Déprécié: la version PHP dépréciée de la fonction.
- Supprimé: la version de la fonction supprimée de PHP.
Règles d'écriture
- Utilisez un langage clair et concis pour éviter les termes obsolètes.
- Fournissez suffisamment d'informations pour permettre aux développeurs de comprendre comment fonctionnent les fonctions.
- Utilisez le format d'annotation DocBlock.
Cas pratiques
/ **
* Calculez la moyenne des deux nombres.
*
* @param float $ num1 premier numéro * @param float $ num2 deuxième numéro * @return float moyen * /
moyenne de la fonction (float $ num1, float $ num2): float
{
retour ($ num1 + $ num2) / 2;
} Autres conseils
- Utilisez des extraits de code pour démontrer l'utilisation de la fonction.
- Lien des fonctions ou des classes liées à la documentation pour fournir plus d'informations.
- Fournir les invites de type autant que possible pour améliorer la lisibilité du code.
- Examiner régulièrement les documents pour garantir l'exactitude et la cohérence.
