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:
Acacha Wiki/**
* This is a DocBlock comment
*/
function foo()
{
}
A DocBlock contains three basic segments in this order:
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:
@throws @todo @uses & @used-by @var @version
Llista completa:
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
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
*/
*<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
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
@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
<?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:
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) {
}
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:
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)
<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>