PHPDoc

Den aktuelle version af siden er endnu ikke blevet gennemgået af erfarne bidragydere og kan afvige væsentligt fra den version , der blev gennemgået den 28. august 2019; checks kræver 5 redigeringer .

PHPDoc er en tilpasset Javadoc dokumentationsstandard til brug i PHP .

Beskrivelse

Mens kommentarstandarden kun har en formel status, er det dog planlagt at konsolidere den som en af udviklingsstandarderne for PHP-frameworks, der udvikles af PHP-FIG-gruppen. Standarden, der udarbejdes, vil modtage nummeret PSR-5 [1] . PHPDoc understøtter både objektorienteret og proceduremæssig kode i dokumenter.

Et separat phpDocumentor- program er blevet oprettet til at fortolke koden .

phpDocumentor er et program, der er i stand til at parse PHP-kildekode og DocBlock-kommentarer for at generere et komplet sæt API-dokumentation [2] .

PHPDoc-komponenter

Doc-blokke

Doc-blocks ( eng. DocBlock comments ) er kommentarer med flere linjer i stil med C -sproget , placeret før det dokumenterede element. Det første tegn i en kommentar (og i begyndelsen af kommentarlinjerne) skal være * . Blokke er adskilt af tomme linjer.

Et eksempel på Doc-blok til foo()-funktionen:

PHPDoc-funktioner

Support til den seneste PHP- version
Arbejde med UML diagram klasser
Fuld tekstsøgning
CI-støtte ud af æsken
Mere kontrol med DocBlocks

Versioner af PHPDoc

Nuværende version af PHPDocumentator 3, Repository

Funktioner

Kompatibel med PHP 7.0+ , fuld understøttelse af navnerum, loops og mere.
Docblock over typer , docblocks er mere eksplicit om typer, ikke alle formater understøttes af php.
Gengiver et hvilket som helst tag , nogle tags tilføjer ekstra funktionalitet til phpDocumentor (som @link).
Lavt hukommelsesforbrug , maksimalt hukommelsesforbrug til små projekter er mindre end 20 MB, for mellemstore projekter er det 40 MB, og for store rammer er det 100 MB.
Inkrementel parsing. Ved at gemme en strukturfil fra en tidligere kørsel, er der et ekstra ydelsesboost på op til 80 % ud over stigningen i behandlingshastigheden nævnt ovenfor.
Enkel oprettelse af en skabelon gør det muligt at kalde 1 opgave og redigere 3 filer.
To-trins proces : phpDocumentor opretter først en cache med applikationsstrukturen, før den genererer output. Giver dig mulighed for at bruge dine egne værktøjer eller formatere.
Generel support , med mere statisk parsing i php, er typer blevet mere komplekse. phpDocumentor forstår disse typer. Og vil vise dem som førsteklasses typer [2] .

Ansøgning

Når du udvikler dine egne store projekter, hvis alle finesser ikke kan huskes, ligesom når du færdiggør andres projekter, skal du ofte kigge ind i tidligere skrevet kode. Dette giver dig mulighed for mere præcist at forestille dig de returnerede, oprettede objekter, og hvad du kan gøre med dem. Da PHP har implicit type casting , er fejl potentielt mulige, når der udføres operationer på objekter af forskellige typer. På stærkt indtastede sprog vil dette ikke ske - programmet vil simpelthen ikke kompilere.

For at undgå dette bruges PHPDoc og andre lignende teknologier. Lad os sige, at vi har en kode :

... $eventData = new EventData (); $eventData -> afsender = $controller ; $eventData -> name = 'onDelete' ; $eventData -> group = 'global' ; $eventData -> arguments = array ( 'id' => 15 ); $eventDispatcher -> triggerEvent ( $eventData ); ...

En tredjepartsudvikler, der læser denne kode, ved muligvis ikke, hvad $controller indeholder, men IDE'en vil fortælle ham, om den understøtter PHPDoc. Det vil sige ved at skrive: $controller->- vi kan se, hvad der er indeni. Som et resultat er der ingen grund til at dykke ned i junglen af kode for at finde ud af, hvad der sendes af dette objekt og i hvilken type.

Noter

↑ fig-standards/phpdoc.md phpDocumentor/fig-standards // GitHub . Dato for adgang: 20. december 2015. Arkiveret fra originalen 31. marts 2016. (ubestemt)
↑ 1 2 Docker Hub . hub.docker.com _ Hentet: 24. september 2022. (ubestemt)