phpDocumenter

Voor commentaar in PHP-scripts gelden nauwelijks regels en niemand doet het hetzelfde. Dit kan tot een chaotische documentatie leiden.

Voor die reden hebben we phpDocumenter (http://phpdoc.org/), om nuttige documentatie te genereren.
phpDocumenter heeft nuttige tags waarmee je allemaal dingen kunt aangeven, zoals input en output. Ik ga nu alleen die tags behandelen, die ook handig zijn als je phpDocumenter niet gebruikt om documentatie aan te maken. Ik kan ze natuurlijk niet allemaal behandelen, dus kijk op http://www.phpdoc.org/docs/latest/index.html als je ze allemaal wilt weten.

Algemeen
Een normaal phpDocumenter document is opgebouwd als volgt:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
<?php
/**
 * [Short description]
 *
 * [Long description]
 *
 * [Tags]
 */

?>


Versiebeheer
Bij grotere projecten volgen verschillende versies elkaar snel op. Met de tag @version kan je een versienummer aangeven.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
@version 2

Elke versie verschilt van andere versies. Daarvoor zijn het immers verschillende versies... Voor het markeren van onderdelen die nieuw zijn, gebruik je de tag @since gevolgd door een versienummer.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
@since 1.2

Zijn bepaalde onderdelen verouderd, dan markeer je die met @deprecated. Hiermee geef je aan dat een onderdeel beter niet meer kan worden gebruikt of dat het in een nieuwe versie zal worden verwijderd. Achter de tag noem je een versienummer en/of geef je een toelichting.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
@deprecated 5.3.0


Auteur
Met de tag @author geef je aan wie een PHP-script heeft geschreven.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
@author Koen V.

Het is gebruikelijk om hieraan een e-mailadres toe te voegen, zodat als er vragen zijn de auteur makkelijk te bereiken is.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
@author Koen V. <koen@example.com>

Als je in een team werkt, of er zijn meerdere auteurs, dan gebruik je meerdere keren de tag @author.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
@author Koen V. <koen@example.com>
@author Piet Pietersen <piet@example.com>


Licentie
Als er een licentie op je script zit, kan je de tag @license gebruiken. Je kan daarin verwijzen naar URL, naam en, als er meerdere versies zijn, de versie.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
@license http://www.php.net/license/3_01.txt PHP License v3.01


Invoer en uitvoer
Nu komen de belangrijkste tags. De resultaten voor in- en output. Voor de input, datgene dat je tussen de haakjes zet, gebruik je @param. Achter deze tag zet je achtereenvolgens het datatype, de naam en een eventuele toelichting. Voor de return gebruik je @return met daarachter een datatype en eventueel een beschrijving. Zijn er meerdere datatypes mogelijk? Dan scheid je ze door een pipeline (|).
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * Bedrag in euronotatie
 *
 * @param float $bedrag getal dat moet worden weergegeven
 * @param integer $decimalen aantal decimalen, niet vereist
 * @return string Het bedrag in euro's.
 */
function get_bedrag_in_euro($bedrag, $decimalen = 2)
{
    $bedarg = number_format($bedrag, $decimalen, ',', '.');
    $bedrag = '&euro; ' . $bedrag;
    return $bedrag;
}

Je kan de parameters het beste noemen in de volgorde waarin ze moeten worden doorgegeven.

Hyperlinks
Zelf documentatie schrijven heeft niet zoveel zin als die er al is. Daarom kan je met @link links opnemen naar webpagina's.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
/**
 * Databaseconnecter
 *
 * Deze klasse is voor het afhandelen van MySQL-databaseverbindingen.
 *
 * @link http://dev.mysql.com/doc/refman/5.0/en/apis-php-mysqli.html
 * @link http://www.php.net/manual/en/class.mysqli.php
 * @link http://www.phpnet/manual/en/mysql.connect.php
 */

class databaseconnector extends mysqli
{
    
}

?>


Aan het einde van je zware dag
Als een PHP-script nog niet helemaal af is, dan heb je wel iets anders te doen dan documentatie schrijven. Dan is er toch één onmisbare tag: @todo. Met @todo kun je bijhouden wat er nog gedaan moet worden. Je kan ook meerdere @todo tags toevoegen.
Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
/**
 * E-mailadres valideren
 *
 * @todo E-mailadressen van meer dan 256 karakters verbieden.
 * @todo Lokale namen van meer dan 64 karakters in e-mailadressen verbieden
 *
 * @param string $emailadres
 * @return boolean
 */

function checkemail($email)
{
    
}

?>


Onthoud bij alles dat als je de /** inkort tot /* (met één sterretje) dat het commentaar in phpDocumenter verborgen blijft.

Andere parsers
Ik heb nu alleen maar phpDocumenter behandelt, maar er bestaan ook andere documentatie parsers, zoals Sami(https://github.com/fabpot/Sami).

« Lees de omschrijving en reacties

Inhoudsopgave

  1. Inleiding
  2. Commentaar in vier stijlen
  3. Tabellen in commentaar
  4. phpDocumenter

PHP tutorial opties

 
 

Om de gebruiksvriendelijkheid van onze website en diensten te optimaliseren maken wij gebruik van cookies. Deze cookies gebruiken wij voor functionaliteiten, analytische gegevens en marketing doeleinden. U vindt meer informatie in onze privacy statement.