Ricerca…
Sintassi
- @api
- @author [nome] [<indirizzo email>]
- @copyright <description>
- @deprecated [<"Versione semantica">] [: <"Versione semantica">] [<descrizione>]
- @esempio [URI] [<descrizione>]
- {@esempio [URI] [: <start> .. <end>]}
- @inheritDoc
- @interno
- {@internal [description]}}
- @license [<identificatore SPDX> | URI] [nome]
- @method [return "Type"] [name] (["Type"] [parametro], [...]) [descrizione]
- @package [livello 1] \ [livello 2] \ [ecc.]
- @param ["Tipo"] [nome] [<descrizione>]
- @property ["Tipo"] [nome] [<descrizione>]
- @return <"Tipo"> [descrizione]
- @vedi [URI | "FQSEN"] [<descrizione>]
- @since [<"Versione semantica">] [<descrizione>]
- @throws ["Tipo"] [<descrizione>]
- @todo [descrizione]
- @uses [file | "FQSEN"] [<descrizione>]
- @var ["Tipo"] [nome_elemento] [<descrizione>]
- @version ["Versione semantica"] [<descrizione>]
- @filesource: include il file corrente nei risultati di analisi phpDocumentor
- @link [URI] [<description>] - Il tag link aiuta a definire la relazione o il collegamento tra elementi strutturali .
Osservazioni
"PHPDoc" è una sezione di documentazione che fornisce informazioni sugli aspetti di un "elemento strutturale" - PSR-5
Le annotazioni PHPDoc sono commenti che forniscono metadati su tutti i tipi di strutture in PHP. Molti IDE popolari sono configurati per impostazione predefinita per utilizzare le annotazioni PHPDoc per fornire informazioni sul codice e identificare possibili problemi prima che si verifichino.
Mentre le annotazioni PHPDoc non fanno parte del core PHP, attualmente mantengono lo stato di bozza con PHP-FIG come PSR-5 .
Tutte le annotazioni PHPDoc sono contenute in DocBlocks dimostrate da una linea multipla con due asterischi:
/**
*
*/
La versione completa degli standard PHP-FIG è disponibile su GitHub .
Aggiunta di metadati alle funzioni
Le annotazioni a livello di funzione aiutano gli IDE a identificare valori di ritorno o codice potenzialmente pericoloso
/**
* 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(/* ... */);
}
Aggiunta di metadati ai file
I metadati a livello di file si applicano a tutto il codice all'interno del file e devono essere posizionati nella parte superiore del file:
<?php
/**
* @author John Doe ([email protected])
* @copyright MIT
*/
Ereditare i metadati dalle strutture parent
Se una classe estende un'altra classe e usa gli stessi metadati, fornirla a @inheritDoc è un modo semplice per utilizzare la stessa documentazione. Se più classi ereditano da una base, solo la base dovrebbe essere cambiata affinché i bambini siano interessati.
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;
}
}
Descrivere una variabile
La parola chiave @var può essere utilizzata per descrivere il tipo e l'utilizzo di:
- una proprietà di classe
- una variabile locale o globale
- una classe o costante globale
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;
...
}
Il tipo può essere uno dei tipi di PHP integrati o una classe definita dall'utente, inclusi gli spazi dei nomi.
Il nome della variabile deve essere incluso, ma può essere omesso se il docblock si applica a un solo elemento.
Descrivere i parametri
/**
* 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)
{
}
collezioni
PSR-5 propone una forma di notazione in stile generico per le raccolte.
Sintassi generica
Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>
I valori in una collezione POSSONO anche essere un altro array e anche un'altra Collection.
Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>
Esempi
<?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()
]);