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)
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
<?php
/**
* [Short description]
*
* [Long description]
*
* [Tags]
*/
?>
/**
* [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)
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)
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)
1
@deprecated 5.3.0
Auteur
Met de tag @author geef je aan wie een PHP-script heeft geschreven.
Code (php)
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.
Als je in een team werkt, of er zijn meerdere auteurs, dan gebruik je meerdere keren de tag @author.
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)
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)
1
2
3
4
5
6
7
8
9
10
11
12
13
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 = '€ ' . $bedrag;
return $bedrag;
}
* 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 = '€ ' . $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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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
{
}
?>
/**
* 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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)
{
}
?>
/**
* 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).