Doxygen: Wie Klassenvariablen in PHP zu beschreiben?

Question

Ich versuche, Doxygen zu verwenden, um PHP-Code in XML-Ausgabe zu analysieren. Doxygen analysiert die Beschreibung der Klassenmitgliedsvariablen nicht.

Hier ist meine Probe PHP-Datei:

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

Beachten Sie, dass Kommentar eine kurze Beschreibung und Variablentyp hat. Hier ist xml i aus dieser Quelle bekam:

<?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> 

Weder Beschreibung oder Typ analysiert wurden. Wie kann ich das beheben?

Answer 1

ich einen Eingangsfilter bin mit typehints aus der @var Annotation inline mit Variablendeklaration einfügen und entfernen Sie die @var Annotation als eine verschiedene Bedeutung in Doxygen hat. Weitere Informationen finden Sie unter Fehler #626105.

Da Doxygen C-like Parser verwendet, kann der Eingangsfilter bei der Ausführung Typen erkennen.

<?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; 

Dies ist ein quick hack und wahrscheinlich Fehler haben, funktioniert es nur für meinen Code:

Sie Eingangsfilter mit INPUT_FILTER Option in Ihrem Doxyfile aktivieren. Speichern Sie den obigen Code in der Datei php_var_filter.php und setzen Sie den Filterwert auf "php php_var_filter.php".

Answer 2

Es scheint ein Fehler in Doxygen zu sein. Ich habe das gleiche Problem mit der Dokumentation in HTML.

Was zur Zeit arbeitet, ist:

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

Aber diese Kommentare werden nicht von NetBeans IDE als Dokumentation des Feldes erkannt.

Answer 3

Dies ist zwar keine direkte Antwort auf Ihre Frage: Wenn Sie das richtige Werkzeug für den Job verwenden können, werfen Sie einen Blick auf DocBlox. Es erzeugt auch ein XML-Dokument für die weitere Umwandlung in HTML oder ein anderes Anzeigeformat und funktioniert sehr gut für PHP. Es wird auch nicht Ihre übliche Docblock-Verwendung brechen.

Als Beispiel Ausgabe, überprüfen Sie die Zend Framework API documentation.

Answer 4

Der Block wird korrekt zugeordnet, wenn Sie @var auslassen. Das gibt nirgends den Typ zu deklarieren, was ärgerlich ist, aber zumindest funktioniert die Beschreibung.

Test-Version: Doxygen 1.7.1

Answer 5

hatte ich das gleiche Problem, also habe ich ein einfaches Eingangsfilter erstellt, die die grundlegende Syntax von

dreht

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

in

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

die ohnehin überflüssig wäre. Auf diese Weise kann die Eclipse-IDE den gleichen Docblock wie Doxygen verwenden.

Sie können die Eingangsfilter von hier herunterladen:

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

die Doxygen Manual Siehe, wie ein Eingangsfilter zu verwenden.

Das Tool entkommt auch Backslashes in Docblocks, so dass Sie dort Namespaces verwenden können.

Answer 6

Vielen Dank an Goran für seinen Doxygenfilter!

Fügen Sie Zend Studio-Stil-Array-of-Objekte @param Typen in doxygen Dokumentation: die gleiche Idee erstreckt, ein bisschen, als auch eine ordnungsgemäße Dokumentation der Funktionsparameter zu machen

// 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); 

int Include/float/Doppel/string @param Typen in doxygen Dokumentation:

// 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); 

Beide oben regexps arbeiten natürlich auch mit Funktionen mehr als ein Argument nimmt. Auch nur ein schneller Hack, der für unseren Code funktioniert, hofft, dass es jemand anderem hilft.

Answer 7

für Windows-Benutzer ohne installierte PHP kann nützlich Verwendung für den Link compiled to executable php_var_filter.php doxygen filter script von answer