Doxygen: cómo describir las variables de los miembros de la clase en php?

Question

Estoy tratando de usar doxygen para analizar el código php en salida xml. Doxygen no analiza la descripción de las variables de los miembros de la clase.

Aquí es mi muestra archivo PHP:

<?php 
class A 
{ 
    /** 
     * Id on page. 
     * 
     * @var integer 
     */ 
    var $id = 1; 
} 
?> 

Nota que el comentario tiene una breve descripción y tipo de variable. Aquí es XML que tengo de esta fuente:

<?xml version='1.0' encoding='UTF-8' standalone='no'?> 
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.7.2"> 
    <compounddef id="class_a" kind="class" prot="public"> 
<compoundname>A</compoundname> 
    <sectiondef kind="public-attrib"> 
    <memberdef kind="variable" id="class_a_1ae97941710d863131c700f069b109991e" prot="public" static="no" mutable="no"> 
    <type></type> 
    <definition>$id</definition> 
    <argsstring></argsstring> 
    <name>$id</name> 
    <initializer> 1</initializer> 
    <briefdescription> 
    </briefdescription> 
    <detaileddescription> 
    </detaileddescription> 
    <inbodydescription> 
    </inbodydescription> 
    <location file="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" line="11" bodyfile="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" bodystart="11" bodyend="-1"/> 
    </memberdef> 
    </sectiondef> 
<briefdescription> 
</briefdescription> 
<detaileddescription> 
</detaileddescription> 
<location file="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" line="5" bodyfile="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" bodystart="4" bodyend="12"/> 
<listofallmembers> 
    <member refid="class_a_1ae97941710d863131c700f069b109991e" prot="public" virt="non-virtual"><scope>A</scope><name>$id</name></member> 
</listofallmembers> 
    </compounddef> 
</doxygen> 

Ni descripción o tipo fueron analizados. ¿Cómo puedo solucionar esto?

Answer 1

estoy usando un filtro de entrada para insertar typehints de la línea de anotación @var con declaración de variables, y quitar la anotación @ var ya que tiene significado diferente en Doxygen. Para obtener más información, consulte el error #626105.

Como Doxygen usa un analizador tipo C, cuando se ejecuta el filtro de entrada puede reconocer los tipos.

<?php 
$source = file_get_contents($argv[1]); 

$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#'; 
$replac = '${2} */ ${3} ${1} ${4}'; 
$source = preg_replace($regexp, $replac, $source); 

echo $source; 

Ésta es una quick hack, y, probablemente, tener errores, simplemente funciona para mi código:

puede habilitar el filtro de entrada con INPUT_FILTER opción en su Doxyfile. Guarde el código anterior en el archivo llamado php_var_filter.php y establezca el valor del filtro en "php php_var_filter.php".

Answer 2

Parece ser un error en Doxygen. Tengo el mismo problema con la documentación en HTML.

Lo que funciona actualmente es:

class A 
{ 
    var $id = 1; /**< Id on page. */ 
} 

Pero estos comentarios no son reconocidos por el IDE NetBeans como documentación de campo.

Answer 3

Si bien esta no es una respuesta directa a su pregunta: Si tiene la libertad de utilizar la herramienta adecuada para el trabajo, eche un vistazo a DocBlox. También genera un documento XML para una mayor transformación en HTML o cualquier otro formato de visualización y funciona muy bien para PHP. Tampoco romperá tu uso habitual de docblock.

Como salida de ejemplo, consulte Zend Framework API documentation.

Answer 4

El bloque se asociará correctamente si omite @var. Eso no da lugar para declarar el tipo, lo cual es molesto, pero al menos la descripción funcionará.

versión de prueba: Doxygen 1.7.1

Answer 5

he tenido el mismo problema, por lo que he creado un filtro de entrada simple que convierte la sintaxis básica de

/** 
* @var int 
*/ 
public $id; 

en

/** 
* @var int $id 
*/ 
public $id; 

que sería redundante de todos modos. De esta forma, el Eclipse IDE puede usar el mismo bloque de documentos que Doxygen.

Puede descargar el filtro de entrada desde aquí:

https://bitbucket.org/tamasimrei/misc-tools/src/master/doxygen/filter.php

Véase el Doxygen Manual sobre el uso de un filtro de entrada.

La herramienta también escapa barras invertidas en docblocks, por lo que podría usar espacios de nombres allí.

Answer 6

Muchas gracias a Goran por su filtro doxygen! La extensión de la misma idea un poco, para que la documentación apropiada de los parámetros de función, así:

Incluir Zend Studio estilo-matriz-de-objetos @param tipos de documentación doxygen:

// Change the following: 
// /** @param VarType[] $pParamName Description **/ 
// function name(array $pParamName) { 

// Into: 
// /** @param array $pParamName Description **/ 
// function name(VarType[] $pParamName) { 
$regexp = '#\@param\s+([^\s]+)\[\]\s+(\$[^\s]+)\s+([^/]+)/\s+(public|protected|private)?\s+function\s+([^\s]+)\s*\(([^)]*)array\s+\2([^)]*)\)(\s+){#s'; 
$replac = '@param array ${2} ${3}/ ${4} function ${5} (${6} ${1}[] ${2}${7})${8}{'; 
$lSource = preg_replace($regexp, $replac, $lSource); 

Incluir int/flotador/tipos dobles/cadena @param en la documentación Doxygen:

// Change the following: 
// /** @param (int|float|double|string) $pParamName Description **/ 
// function name($pParamName) { 

// Into: 
// /** @param (int|float|double|string) $pParamName Description **/ 
// function name((int|float|double|string) $pParamName) { 
$regexp = '#\@param\s+(int|float|double|string)\s+(\$[^\s]+)\s+([^/]+)/\s+(public|protected|private)?\s+function\s+([^\(\s]+)\s*([^)]*)(\(|,)\s*\2([^)]*)\)(\s+){#s'; 

$replac = '@param ${1} ${2} ${3}/ ${4} function ${5}${6}${7}${1} ${2}${8})${9}{ '; //${6}${1} ${2}${7})${8}{'; 
$lSource = preg_replace($regexp, $replac, $lSource); 

Tanto de las expresiones regulares anteriores también funcionan de forma natural con las funciones de tomar más de un argumento. También solo un truco rápido, que funciona para nuestro código, espero que ayude a otra persona.

Answer 7

para usuarios de Windows sin PHP instalado puede ser útil el uso de compiled to executable php_var_filter.php doxygen filter scriptanswer