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()
]);


Modified text is an extract of the original Stack Overflow Documentation
Autorizzato sotto CC BY-SA 3.0
Non affiliato con Stack Overflow