Szukaj…
Składnia
- @api
- @author [nazwa] [<adres e-mail>]
- @copyright <opis>
- @deprecated [<„Semantic Version”>] [: <„Semantic Version”>] [<description>]
- @przykład [URI] [<opis>]
- {@example [URI] [: <start> .. <end>]}
- @inheritDoc
- @wewnętrzny
- {@internal [description]}}
- @license [<identyfikator SPDX> | URI] [nazwa]
- @method [return „Type”] [name] ([„Type”] [parametr], [...]) [opis]
- @ pakiet [poziom 1] \ [poziom 2] \ [itd.]
- @param [„Type”] [name] [<description>]
- @property [„Type”] [name] [<description>]
- @return <„Type”> [opis]
- @ patrz [URI | „FQSEN”] [<opis>]
- @since [<„Semantic Version”>] [<description>]
- @throws [„Type”] [<description>]
- @todo [opis]
- @uses [plik | „FQSEN”] [<opis>]
- @var [„Typ”] [nazwa_elementu] [<opis>]
- @version [„Wersja semantyczna”] [<opis>]
- @ plik - Zawiera bieżący plik w wynikach analizy phpDocumentor
- @link [URI] [<opis>] - Znacznik linku pomaga zdefiniować relację lub połączenie między elementami konstrukcyjnymi .
Uwagi
„PHPDoc” to sekcja dokumentacji, która zawiera informacje na temat aspektów „elementu strukturalnego” - PSR-5
Adnotacje PHPDoc to komentarze, które dostarczają metadane dotyczące wszystkich typów struktur w PHP. Wiele popularnych IDE jest domyślnie skonfigurowanych do korzystania z adnotacji PHPDoc w celu zapewnienia wglądu w kod i identyfikacji potencjalnych problemów, zanim się pojawią.
Chociaż adnotacje PHPDoc nie są częścią rdzenia PHP, obecnie mają status wersji roboczej z PHP-FIG jako PSR-5 .
Wszystkie adnotacje PHPDoc są zawarte w DocBlocks, które są demonstrowane przez wiele linii z dwiema gwiazdkami:
/**
*
*/
Pełny projekt standardów PHP-FIG jest dostępny na GitHub .
Dodawanie metadanych do funkcji
Adnotacje na poziomie funkcji pomagają IDE identyfikować zwracane wartości lub potencjalnie niebezpieczny kod
/**
* 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(/* ... */);
}
Dodawanie metadanych do plików
Metadane na poziomie pliku dotyczą całego kodu w pliku i powinny być umieszczone na górze pliku:
<?php
/**
* @author John Doe ([email protected])
* @copyright MIT
*/
Dziedziczenie metadanych ze struktur nadrzędnych
Jeśli klasa rozszerza inną klasę i @inheritDoc tych samych metadanych, zapewnienie jej @inheritDoc jest prostym sposobem na użycie tej samej dokumentacji. Jeśli wiele klas dziedziczy z bazy, tylko podstawa musiałaby zostać zmieniona, aby zmiany dotyczyły dzieci.
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;
}
}
Opisanie zmiennej
@var kluczowego @var można użyć do opisania rodzaju i zastosowania:
- własność klasy
- zmienna lokalna lub globalna
- stała klasowa lub globalna
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;
...
}
Typem może być jeden z wbudowanych typów PHP lub klasa zdefiniowana przez użytkownika, w tym przestrzenie nazw.
Należy podać nazwę zmiennej, ale można ją pominąć, jeśli docblock dotyczy tylko jednego elementu.
Opisywanie parametrów
/**
* 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)
{
}
Kolekcje
PSR-5 proponuje formę notacji w stylu Generics dla kolekcji.
Składnia ogólna
Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>
Wartości w kolekcji MOGĄ być nawet kolejną tablicą, a nawet inną kolekcją.
Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>
Przykłady
<?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()
]);