Salta el contingut

MP08 - UF4: Control de versions i documentació

Documentació de Codi amb phpDocumentor

Crearem la documentació del codi dels nostres programes amb phpDocumentor. Per això accedirem a la pàgina oficial de phpDocumentor i en farem la instal·lació al nostre ordinador. La versió disponible el, gener de 2024, era la 3.0. La versió disponible el, gener de 2025, és la 3.0.

Segons se'ns proposa, hi ha tres formes d'instal·lar-lo, una d'elles amb un Docker. Si tenim temps, ho farem més endavant. De moment escollirem la tercera opció que diu Stand-alone, downloading a PHAR.

Aquesta eina utilitza php i té uns determinats requeriments:

  • PHP 8.1.2 o superior

  • L'extensió mbstring de php

  • L'extensió xml de php

  • Opcionalment

Instal·lació de phpDocumentor de forma autònoma, baixant un PHAR

Podeu baixar l'últim fitxer PHAR a https://phpdoc.org/phpDocumentor.phar o una versió específica a https://github.com/phpDocumentor/phpDocumentor/releases.

El fitxer phar es pot utilitzar invocant PHP directament i proporcionant el fitxer phar com a paràmetre:

Utilitzem el fitxer directament
php phpDocumentor.phar run -d . -t docs/api

podem posar-lo, també, en algun directori que tinguem a la variable del PATH, donar-li permisos d'execució, i cridar-lo directament, havent-li posat de nom phpDocumentor, sense l'extensió.

Utilitzem el fitxer directament si està en un directori del PATH
$ phpDocumentor run -d . -t docs/api

Per tant...

Possible instal·lació en Linux

Descarreghem el fitxer a /usr/local/bin
sudo wget https://phpdoc.org/phpDocumentor.phar -O /usr/local/bin/phpDocumentor
Li posem els permisos necessaris
sudo chmod a+x /usr/local/bin/phpDocumentor

Ja el podem utilitzar directament indicant el directori on tenim el projecte i el directori on volem la documentació generada:

  • -d indica el directori on tenim el codi amb els comentaris

  • -t indica el directori on se'ns generarà el codi accessible per html.

Utilitzem el phpDocumentor
phpDocumentor run -d projecte -t documentacio

Una vegada instal·lat ja podrem utilitzar-lo.

Per crear, de forma fàcil la documentació per PHPDocumentor, VisualStudioCode té moltes extensions possibles. Només cal buscar php Doc i ens n'apareixeran unes quantes.