Salta el contingut

phpDocumentor - Personalització de l'entorn

w# MP08 - UF4: Control de versions i documentació

phpDocumentor: DockBlock

Un DocBlock és una peça de documentació del vostre codi font que us informa quina és la funció d'una determinada classe, mètode o un altre element estructural.

Què es pot documentar al vostre codi font?

Abans de parlar de com és un DocBlock, primer anem a ampliar el que podeu documentar amb ells. phpDocumentor segueix la definició de PHPDoc i reconeix els següents elements estructurals :

  • Funció

  • Constant

  • Classe

  • Interfície

  • Trait

  • Constant de classe

  • Propietat

  • Mètode

A més de l'anterior, l'estàndard PHPDoc també admet DocBlocks per a fitxers i declaracions include/require, tot i que el mateix PHP ho reconeix com una estructura de llenguatge.

Cadascun d'aquests elements pot tenir associat exactament un DocBlock, que el precedeix directament. No hi ha cap codi ni comentaris entre un DocBlock i l'inici de la definició d'un element.

Com és un DocBlock?

Els DocBlock sempre s'inclouen en un tipus de comentari particular, anomenat DocComment . Un DocComment comença amb /** (obre el comentari) i acaba amb */(tanca el comentari). Cada línia entre l'inici i el final hauria de començar amb un asterisc (*).

Per exemple:

<?php
/**
 * Això és un DocBlock.
 */
function funcioAssociada()
{
}

Els DocBlocks es divideixen en tres parts. Cadascuna d'aquestes parts és opcional, tret que la Descripció no pot existir sense un Resum.

  • Resum: El Resum, de vegades anomenat descripció breu, proporciona una breu introducció a la funció de l'element associat. Un resum acaba quan es troba alguna de les situacions següents:

    • un punt ., seguit d'un salt de línia

    • o una línia en blanc (comentari).

  • Descripció: La descripció, de vegades anomenada descripció llarga, pot proporcionar més informació. Alguns exemples d'informació addicional són: una descripció de l'algorisme d'una funció, un exemple d'ús o una descripció de com s'adapta una classe a tota l'arquitectura de l'aplicació. La descripció acaba quan es troba la primera etiqueta en una línia nova o quan es tanca el DocBlock.

  • Etiquetes i anotacions: Aquests ofereixen una manera de proporcionar de manera concisa i uniforme metainformació sobre l'element associat. Les etiquetes poden, per exemple, descriure el tipus d'informació que retorna un mètode o funció. Cada etiqueta va precedida d'un signe at ( @) i comença en una línia nova.

Exemple de DockBlock
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<?php
/**
* Un resum que informa a l'usuari de què fa l'element associat.
*
* Una *descripció*, que pot abastar diverses línies, per aprofundir en
* els detalls d'aquest element i per proporcionar informació de fons
* o referències textuals.
*
* @param string $elParametre Amb una *descripció* d'aquest argument,
*                            també podem abastar diverses línies.
*
* @return void
*/
function laMevaFuncio($elParametre)
{
}

Repassem aquest exemple línia per línia i discutim quin és quina,

  • Línia 2: mostra que un DocBlock comença amb la seqüència d'obertura /**.

  • Línia 3: té un exemple de resum. Normalment es tracta d'una única línia, però pot cobrir diverses línies sempre que no s'arribi al final del resum, tal com es defineix al capítol anterior.

  • Línia 5 , 6 i 7: mostra un exemple de descripció, que pot abastar diverses línies i es pot formatar amb el llenguatge de marques Markdown. Amb Markdown podeu fer que el text sigui en negreta, cursiva, afegir llistes numerades i fins i tot proporcionar codeexemples.

  • Línia 9 i 12: mostra què podeu incloure, als vostres DocBlocks, per proporcionar informació addicional sobre l'element següent. En aquest exemple, declarem que l'argument $elParametre és de tipus string, amb una descripció del que representa aquest argument, i declarem que el valor de retorn d'aquest mètode és void, el que significa que no es retornarà cap valor.

  • Línia 13: mostra la seqüència de tancament */, que és la mateixa que la d'un comentari de diverses línies (/* .. */).

Accés a un exemple de documentació

Per a documentar el codi caldrà seguir el que se'ns explica a Documentation

Pots trobar un programa amb funcions en llenguate php al següent enllaç: Exemple de programa amb funcions en php i un programa amb Classes en llenguate php al següent enllaç: Exemple de programa amb classes en php

Podeu trobar més informació sobre les etiquetes a https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/

Exemple generat

El trobareu aquí

Accés a un tutorial

Trobareu un tutorial a https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html. És un tutorial antic, però l'important és veure les etiquetes i el seu ús.

Si voleu canviar els estils, podeu mirar la pàgina del projecte a https://docs.phpdoc.org/guide/features/theming/custom-styling.html