Zoeken…
Syntaxis
- @api
- @author [naam] [<e-mailadres>]
- @copyright <beschrijving>
- @deprecated [<"Semantische versie">] [: <"Semantische versie">] [<beschrijving>]
- @example [URI] [<description>]
- {@example [URI] [: <start> .. <end>]}
- @inheritDoc
- @internal
- {@internal [description]}}
- @license [<SPDX identifier> | URI] [naam]
- @method [retour "Type"] [naam] (["Type"] [parameter], [...]) [beschrijving]
- @package [niveau 1] \ [niveau 2] \ [enz.]
- @param ["Type"] [naam] [<beschrijving>]
- @property ["Type"] [naam] [<beschrijving>]
- @return <"Type"> [beschrijving]
- @see [URI | "FQSEN"] [<beschrijving>]
- @since [<"Semantische versie">] [<beschrijving>]
- @throws ["Type"] [<beschrijving>]
- @todo [beschrijving]
- @uses [bestand | "FQSEN"] [<beschrijving>]
- @var ["Type"] [element_name] [<description>]
- @version ["Semantische versie"] [<beschrijving>]
- @filesource - Neemt het huidige bestand op in phpDocumentor-parserresultaten
- @link [URI] [<description>] - Link-tag helpt de relatie of link tussen structurele elementen te definiëren.
Opmerkingen
"PHPDoc" is een gedeelte van de documentatie dat informatie biedt over aspecten van een "structureel element" - PSR-5
PHPDoc-annotaties zijn opmerkingen die metagegevens bieden over alle soorten structuren in PHP. Veel populaire IDE's zijn standaard geconfigureerd om PHPDoc-annotaties te gebruiken om code-inzichten te bieden en mogelijke problemen te identificeren voordat ze zich voordoen.
Hoewel PHPDoc-annotaties geen deel uitmaken van de PHP-kern, hebben ze momenteel de conceptstatus met PHP-FIG als PSR-5 .
Alle PHPDoc-annotaties zijn opgenomen in DocBlocks die worden aangetoond door een multi-lijn met twee sterretjes:
/**
*
*/
Het volledige ontwerp van de PHP-FIG- normen is beschikbaar op GitHub .
Metadata toevoegen aan functies
Aantekeningen op functieniveau helpen IDE's om retourwaarden of potentieel gevaarlijke code te identificeren
/**
* 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(/* ... */);
}
Metadata toevoegen aan bestanden
Metagegevens op bestandsniveau zijn van toepassing op alle code in het bestand en moeten bovenaan het bestand worden geplaatst:
<?php
/**
* @author John Doe ([email protected])
* @copyright MIT
*/
Metadata overnemen van bovenliggende structuren
Als een klasse een andere klasse uitbreidt en dezelfde metagegevens zou gebruiken, is @inheritDoc een eenvoudige manier om dezelfde documentatie te gebruiken. Als meerdere klassen van een basis erven, hoeft alleen de basis te worden gewijzigd om de kinderen te beïnvloeden.
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;
}
}
Een variabele beschrijven
Het trefwoord @var kan worden gebruikt om het type en gebruik van te beschrijven:
- een klasse-eigenschap
- een lokale of globale variabele
- een klasse of globale constante
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;
...
}
Het type kan een van de ingebouwde PHP-typen zijn of een door de gebruiker gedefinieerde klasse, inclusief naamruimten.
De naam van de variabele moet worden opgenomen, maar kan worden weggelaten als het docblock op slechts één item van toepassing is.
Parameters beschrijven
/**
* 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)
{
}
collecties
PSR-5 stelt een vorm van notatie in Generics-stijl voor collecties voor.
Generieke syntaxis
Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>
Waarden in een verzameling KUNNEN zelfs een andere reeks en zelfs een andere verzameling zijn.
Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>
Voorbeelden
<?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()
]);