Buscar..
Sintaxis
- @api
- @autor [nombre] [<dirección de correo electrónico>]
- @ copyright <descripción>
- @deprecated [<"Versión semántica">] [: <"Versión semántica">] [<descripción>]
- @ejemplo [URI] [<descripción>]
- {@example [URI] [: <start> .. <end>]}
- @inheritDoc
- @interno
- {@internal [descripción]}}
- @license [<identificador SPDX> | URI] [nombre]
- @ método [retorno "Tipo"] [nombre] (["Tipo"] [parámetro], [...]) [descripción]
- @paquete [nivel 1] \ [nivel 2] \ [etc.]
- @param ["Tipo"] [nombre] [<descripción>]
- @ propiedad ["Tipo"] [nombre] [<descripción>]
- @return <"Type"> [descripción]
- @see [URI | "FQSEN"] [<descripción>]
- @since [<"Versión semántica">] [<descripción>]
- @throws ["Tipo"] [<descripción>]
- @todo [descripción]
- @uses [archivo | "FQSEN"] [<descripción>]
- @var ["Type"] [element_name] [<description>]
- @version ["Versión semántica"] [<descripción>]
- @filesource - Incluye el archivo actual en los resultados del análisis phpDocumentor
- @link [URI] [<description>] - La etiqueta de enlace ayuda a definir la relación o enlace entre elementos estructurales .
Observaciones
"PHPDoc" es una sección de la documentación que proporciona información sobre aspectos de un "Elemento estructural" - PSR-5
Las anotaciones de PHPDoc son comentarios que proporcionan metadatos sobre todos los tipos de estructuras en PHP. Muchos IDE populares están configurados de forma predeterminada para utilizar las anotaciones de PHPDoc para proporcionar información sobre el código e identificar posibles problemas antes de que surjan.
Si bien las anotaciones de PHPDoc no forman parte del núcleo de PHP, actualmente tienen el estado de borrador con PHP-FIG como PSR-5 .
Todas las anotaciones de PHPDoc están contenidas en DocBlocks que se demuestran mediante una multilínea con dos asteriscos:
/**
*
*/
El borrador completo de los estándares PHP-FIG está disponible en GitHub .
Añadiendo metadatos a las funciones.
Las anotaciones de nivel de función ayudan a los IDE a identificar valores de retorno o códigos potencialmente peligrosos
/**
* Adds two numbers together.
*
* @param Int $a First parameter to add
* @param Int $b Second parameter to add
* @return Int
*/
function sum($a, $b)
{
return (int) $a + $b;
}
/**
* Don't run me! I will always raise an exception.
*
* @throws Exception Always
*/
function dangerousCode()
{
throw new Exception('Ouch, that was dangerous!');
}
/**
* Old structures should be deprecated so people know not to use them.
*
* @deprecated
*/
function oldCode()
{
mysql_connect(/* ... */);
}
Añadiendo metadatos a archivos
Los metadatos de nivel de archivo se aplican a todo el código dentro del archivo y se deben colocar en la parte superior del archivo:
<?php
/**
* @author John Doe ([email protected])
* @copyright MIT
*/
Heredar metadatos de estructuras padre
Si una clase extiende otra clase y usaría los mismos metadatos, proporcionarla @inheritDoc es una forma sencilla de usar la misma documentación. Si se heredan varias clases de una base, solo será necesario cambiar la base para que los niños se vean afectados.
abstract class FooBase
{
/**
* @param Int $a First parameter to add
* @param Int $b Second parameter to add
* @return Int
*/
public function sum($a, $b) {}
}
class ConcreteFoo extends FooBase
{
/**
* @inheritDoc
*/
public function sum($a, $b)
{
return $a + $b;
}
}
Describiendo una variable
La palabra clave @var se puede usar para describir el tipo y uso de:
- una propiedad de clase
- una variable local o global
- una clase o constante global
class Example {
/** @var string This is something that stays the same */
const UNCHANGING = "Untouchable";
/** @var string $some_str This is some string */
public $some_str;
/**
* @var array $stuff This is a collection of stuff
* @var array $nonsense These are nonsense
*/
private $stuff, $nonsense;
...
}
El tipo puede ser uno de los tipos PHP integrados o una clase definida por el usuario, incluidos los espacios de nombres.
El nombre de la variable debe incluirse, pero puede omitirse si el bloque de documentos se aplica a un solo elemento.
Describiendo parámetros
/**
* Parameters
*
* @param int $int
* @param string $string
* @param array $array
* @param bool $bool
*/
function demo_param($int, $string, $array, $bool)
{
}
/**
* Parameters - Optional / Defaults
*
* @param int $int
* @param string $string
* @param array $array
* @param bool $bool
*/
function demo_param_optional($int = 5, $string = 'foo', $array = [], $bool = false)
{
}
/**
* Parameters - Arrays
*
* @param array $mixed
* @param int[] $integers
* @param string[] $strings
* @param bool[] $bools
* @param string[]|int[] $strings_or_integers
*/
function demo_param_arrays($mixed,$integers, $strings, $bools, $strings_or_integers)
{
}
/**
* Parameters - Complex
* @param array $config
* <pre>
* $params = [
* 'hostname' => (string) DB hostname. Required.
* 'database' => (string) DB name. Required.
* 'username' => (string) DB username. Required.
* ]
* </pre>
*/
function demo_param_complex($config)
{
}
Colecciones
PSR-5 propone una forma de notación de estilo genérico para colecciones.
Sintaxis de genéricos
Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>
Los valores en una Colección PUEDEN ser incluso otra matriz e incluso otra Colección.
Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>
Ejemplos
<?php
/**
* @var ArrayObject<string> $name
*/
$name = new ArrayObject(['a', 'b']);
/**
* @var ArrayObject<int> $name
*/
$name = new ArrayObject([1, 2]);
/**
* @var ArrayObject<stdClass> $name
*/
$name = new ArrayObject([
new stdClass(),
new stdClass()
]);
/**
* @var ArrayObject<string|int|stdClass|bool> $name
*/
$name = new ArrayObject([
'a',
true,
1,
'b',
new stdClass(),
'c',
2
]);
/**
* @var ArrayObject<ArrayObject<int>> $name
*/
$name = new ArrayObject([
new ArrayObject([1, 2]),
new ArrayObject([1, 2])
]);
/**
* @var ArrayObject<int, string> $name
*/
$name = new ArrayObject([
1 => 'a',
2 => 'b'
]);
/**
* @var ArrayObject<string, int> $name
*/
$name = new ArrayObject([
'a' => 1,
'b' => 2
]);
/**
* @var ArrayObject<string, stdClass> $name
*/
$name = new ArrayObject([
'a' => new stdClass(),
'b' => new stdClass()
]);