IMPORTANT: Per accedir als fitxer de subversion: http://acacha.org/svn (sense password). Poc a poc s'aniran migrant els enllaços. Encara però funciona el subversion de la farga però no se sap fins quan... (usuari: prova i la paraula de pas 123456)

Introducció

PHPDoc is an adaptation of Javadoc for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized.[1] It allows external document generators like phpDocumentor, which is the de facto standard implementation,[1] to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.

PHPDoc supports documentation of both object-oriented and procedural code. On August 13, 2013 the PHP Framework Interoperability Group began writing a formal specification (PSR) for PHPDoc.[1]


Recursos:

Dockblock

DocBlock

/**
 * This is a DocBlock comment
 */
function foo()
{
}

A DocBlock contains three basic segments in this order:

  • Short Description
  • Long Description
  • Tags

Exemple extret de:

https://www.sitepoint.com/introduction-to-phpdoc/
<?php
/**
 * Calculates sum of squares of an array
 *
 * Loops over each element in the array, squares it, and adds it to 
 * total. Returns total.
 * 
 * This function can also be implemented using array_reduce();
 * 
 * @param array $arr
 * @return int
 * @throws Exception If element in array is not an integer
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

Recursos:

Tags

  • @api:
  • @author:
  • @category:
  • @copyright:
  • @deprecated:
  • @example:
  • @filesource:
  • @global:
  • @ignore:
  • @internal:
  • @license:
  • @link:
  • @method:
  • @package:
  • @param:
  • @property:
  • @property-read:
  • @property-write:
  • @return:
  • @see:
  • @since:
  • @source:
  • @subpackage:

@throws @todo @uses & @used-by @var @version

Llista completa:

Instal·lació

Es pot instal·lar amb Pear

$ sudo apt-get install php-pear
$ sudo pear upgrade PhpDocumentor

Un cop instal·lat el trobareu disponible a:

/usr/share/php/PhpDocumentor/phpDocumentor/phpdoc.inc

Documentar el codi font

Es fa mitjançant comentaris de documentació (DocBlock) a l'estil de C (molt similar als javadocs).:

/**
 *
 *
 */

Qualsevol altre tipus de comentari serà ignorat per phpdoc. A dins dels comentaris va text simple:


  /**
   * Defies imagination, extends boundaries and saves the world ...all before breakfast!
   */
   function foo()   {
   ...
   }

i també podem passar variables al parser de phpDoc amb

@

Els símbols que van precedits de @ són anomenats tags. Si el símbol està al principi de la línia es tracta d'un tag estàndard i si està entre {} (curly brackets) leshores és una etiqueta inline (inline tag). Un exemple:

     /**
       * {@inlinetag} 
       * this is @not a standardtag - must begin a line.
       * this is a valid {@inlinetag} also
       * @standardtag
       */

html que es pot utilitzar dins dels docblocks

*<b> -- emphasize/bold text
*<code> -- Use this to surround php code, some converters will highlight it
*<br> -- hard line break, may be ignored by some converters
*<i> -- italicize/mark as important
*<kbd> -- denote keyboard input/screen display
*<li> -- list item
*<ol> -- ordered list
*<p> -- If used to enclose all paragraphs, otherwise it will be considered text
*<pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
*<samp> -- denote sample or examples (non-php)
*<ul> -- unordered list
*<var> -- denote a variable name

Variables globals

TODO

Notice this code from sample2.php:

  1.
     /**
  2.
      * Special global variable declaration DocBlock
  3.
      * @global integer $GLOBALS['_myvar'] 
  4.
      * @name $_myvar
  5.
      */ 
  6.
     $GLOBALS['_myvar'] = 6;

In this segment, we can see the two important tags used for documenting global variables. The @global tag is used to tell the parser how to find a global variable declaration. Without this tag, no documentation would be generated for $_myvar. The @global tag can take many forms - be sure to specify the type and global name, with no description, or the parser will generate a warning and fail to document the variable.

Now, parse sample3.php and observe the generated documentation. The @name tag is used to tell the parser how the global variable would be referenced by a global statement in a function.

  1.
     /**
  2.
      * @global integer this is a function-based @global tag,
  3.
      *          because the variable name is missing
  4.
      */
  5.
     function someFunction()
  6.
     {
  7.
         global $_myvar;
  8.
     }

The @global tag here will associate the information with the declared global statements in the function body in the same order of their de

Builtin parameters

@author Especifica o autor do código/classe/função.
@copyright Especifica os direitos autorais.
@version Especifica a versão da classe/função
@deprecated Especifica elementos que não devem ser usados.
@exemple Definir arquivo de exemplo
@ignore Ignorar código
@access Especifica o tipo de acesso(public, protected e private).
@internal Documenta função interna do código
@link link do código www.exemplo.com
@see Pode ser utilizada para realizar uma referência cruzada para outra classe, interface, método, constructor
@since Desde o codigo foi feito
@tutorial Um pequeno tutorial
@name Especifica o apelido(alias)
@package Especifica o nome do pacote pai, isto ajuda na organização das classes
@param Especifica os paramêtros
@return Especifica o tipo de retorno
@subpackage Especifica o nome do pacote filho

Fitxers i classes

   <?php
   /**
    * Pretend this is a file
    *
    * Page-level DocBlock is here because it is the first DocBlock
    * in the file, and is immediately followed by the second
    * DocBlock before any documentable element is declared
    * (function, define, class, global variable, include)
    * @package pagepackage
    */
   /**
    * Here is the class DocBlock
    *
    * The class package is different from the page package!
    * @package classpackage
    */
    class myclass   {
    }
    ?>

On els packages són el que apareixen a la dreta superior:

PHPDocPackages.png

Plantilles Eclipse

Podeu utilitzar les plantilles i autocompletar per afegir comentaris a diferents elements de codi PHP.

Per exemple la funció:

function hora_final($hora, $ConTut) {
}

Si us poseu davant de la funció i escriviu /** seguit d'Enter tindreu:

**
 * 
 * @param $hora
 * @param $ConTut
 * @return unknown_type
 */
function hora_final($hora, $ConTut) {
}

PHPStorm

Té diferents ajudes per a crear codi PHPDoc:

Escriure /** i tot seguit Enter o Alt+Insert

I genera un Stub de PHPDoc automàticament. Us pot ajudar amb els tag escrivint

@

i tot seguit Ctrl+espai.

També és útil el menu Generate amb

Ctrl+Insert

i escollir la opció PHPdocs.

A les settings a Editor->Inspections podeu buscar les einpeccions i activar l'opció:

Missing PHPDoc Comment

També es molt interesaant que podeu veure la documentació de qualsevol funció, mètode, classe, etc sense tenir que navegar a la API o el codi font (per exemple amb Ctr+b), simplement utilitzeu:

Ctrl+q https://www.jetbrains.com/help/phpstorm/2016.2/viewing-inline-documentation.html

També es molt útil la Tool:

> Menú Code > Inspect Code

Podeu escollir el scope (tot el projecte). Un cop executat hi ha un apartat per a PHPDoc i si s'ha marcat la inspection Missing PHPDoc aleshores tindrem una llista de tot el que falta per documentar.

També es pot executar:

> Menu Code > Run inspection by name

I demanar la inspection MIssing PHP Docs.

Recursos:

Eclipse external Tasks

  1. Select Run->External Tools->External Tools Configurations...
  2. In the left hand pane, select Program then the new icon (left-most icon above the pane).
  3. In the right hand pane, select the Main tab.
  4. Enter generate_doc in the Name: field.
  5. Enter the path to the phpdoc cli tool in the Location: field.
  6. Enter any required arguments in the Arguments field, e.g. for the current project input ${project_loc}.
  7. To run the external configuration, select Run.

To rerun the configuration you have a few choices:

  1. Select the External Tools icon from the menu bar then click generate_doc
  2. Select Run->External Tools->generate_doc
  3. Hit Alt+R, E, 1 (assuming generate_doc is the first item in the list, otherwise pick the appropriate number)

API documentators

Ant task per crear la documentació html

<property name="doc.dir" value="doc"/>

<target name="phpdocs" description="Generates phpDocumentor docs">
  <delete dir="${doc.dir}" />
  <exec executable="php">
    <arg value="/usr/share/php/PhpDocumentor/phpDocumentor/phpdoc.inc" />
    <arg value="-f" />
    <arg value="*.php" />
    <arg value="-t" />
    <arg value="${doc.dir}" />
    <arg value="-ti" />
    <arg value="Photo Gallery Documentation" />
  </exec>
</target>

Vegeu també

Enllaços externs