Ein Tool zum Hinzufügen und Abschluss von PHP -Quellcode -Dokumentation [geschlossen

https://stackoverflow.com/questions/1936376

20-09-2019
|

Frage

Ich habe mehrere fertige, ältere PHP -Projekte mit vielen Einschlüssen, die ich im Javadoc/PHPDocumentor -Stil dokumentieren möchte.

Während ich jede Datei manuell durcharbeiten und gezwungen sind, zusammen mit der Dokumentation eine Codeüberprüfung durchzuführen, wäre ich einfach nicht in der Zeit, die an Tools interessiert sind, die mir helfen, die Aufgabe so weit wie möglich zu automatisieren.

Das Werkzeug, an das ich denke, hat idealerweise die folgenden Funktionen:

Nehmen Sie einen PHP -Projektbaum an und teilen Sie mir mit, wo es undokumentierte Dateien, Klassen und Funktionen/Methoden gibt (dh Elemente fehlen den entsprechenden Docblock -Kommentar)
Stellen Sie eine Methode zur Hälfte zur Verfügung, um die fehlenden Docblocks leicht hinzuzufügen Erstellen der leeren Strukturen und im Idealfall öffnen Sie die Datei in einem Editor (intern oder extern, ich kümmert mich nicht darum), damit ich die Beschreibung einfügen kann.

Optional:

Automatische Erkennung von Parametertypen, Rückgabetwerten und dergleichen. Aber das ist nicht wirklich erforderlich.

Die fragliche Sprache ist PHP, obwohl ich mir vorstellen kann, dass ein C/Java -Tool nach einigen Optimierungen möglicherweise PHP -Dateien verarbeiten kann.

Vielen Dank für Ihre tolle Input!

Lösung

Ich finde PHP_Codesniffer kann angeben, wenn es keinen Docblock gibt - siehe Beispiele von Berichten über diese Seite (zitieren eines davon) :

--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR   | Missing file doc comment
 20 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE"
 47 | ERROR   | Line not indented correctly; expected 4 spaces but found 1
 47 | WARNING | Equals sign not aligned with surrounding assignments
 51 | ERROR   | Missing function doc comment
 88 | ERROR   | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

Ich nehme an, Sie könnten PHP_CODESNIFFER verwenden, um mindestens eine Liste aller Dateien/Klassen/Methoden zu erhalten, die keine Dokumentation haben. Soweit ich mich erinnere, kann es XML als Ausgabe erzeugen, was einfacher mit einem automatisierten Tool analysieren kann-dies könnte der erste Schritt eines Docblock-Generators sein ;-)

Auch wenn Sie verwenden Phpdocumentor Kann dies, um die Dokumentation zu generieren, keine Fehler für fehlende Blöcke melden?

Nach ein paar Tests kann es-zum Beispiel auf einem Klassen-Datei mit nicht viel Dokumentation mit dem ausgeführt werden, mit dem --undocumentedelements Option wie folgt:

phpdoc --filename MyClass.php --target doc --undocumentedelements

Gibt dies in der Mitte der Ausgabe:

Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file
WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock.
WARNING in MyClass.php on line 2: no @package tag was used in a DocBlock for class MyClass
WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock.
WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use @package in the first DocBlock to create one
done

Aber auch hier, auch wenn es als Berichtstool nützlich ist, ist es nicht so hilfreich, wenn es darum geht, die fehlenden Docblocks zu generieren ...

Nun kenne ich kein Tool, das die fehlenden Docblocks für Sie vorbereitet wird: Ich verwende im Allgemeinen PHP_CODESNIFFER und/oder PHPDocumentor in meinem kontinuierlichen Integrations-Mekanismus. , von seiner Ideen ...

... was ziemlich gut funktioniert: Im Allgemeinen gibt es täglich nicht mehr als ein paar fehlende Docblocks, sodass die Aufgabe von Hand erledigt werden kann (Und Eclipse PDT bietet eine Funktion, um den DocBlock für eine Methode vorzubereiten, wenn Sie eine bestimmte Datei/Methode bearbeiten.).

Apartart davon, ich kenne kein vollständig automatisches Tool, um Docblocks zu generieren ... aber ich bin mir ziemlich sicher, dass wir es schaffen könnten, ein interessantes Tool mit beiden zu erstellen:

Die Reflexions -API
token_get_all Um die Quelle einer PHP -Datei zu analysieren.

Nach ein bisschen mehr Suche habe ich diesen Blog-Pfosten gefunden (Es ist in Französisch - vielleicht werden einige Leute hier verstehen können) : Ajout automatatique de tags phpdoc à l'Aide de php_beautifier.
Mögliche Übersetzung des Titels: "Automatisch fügen Sie PHPDOC -Tags mit PHP_BEAUTIFIER hinzu" "

Die Idee ist eigentlich nicht schlecht:

Das PHP_Beautifier Tool ist ziemlich nett und leistungsfähig, wenn es darum geht, einen PHP -Code zu formen, der nicht gut formiert ist
- Ich habe es oft für Code verwendet, den ich nicht einmal lesen konnte ^^
Und es kann erweitert werden, indem es das verwendet, was es nennt. "Filter".
- sehen PHP_Beautifier_Filter Für eine Liste der bereitgestellten Filter

Die Idee, die in dem Blog-Post verwendet wird, mit dem ich verlinkte, ist:

Erstellen Sie einen neuen Php_Beautifier -Filter, der die folgenden Token erkennt:
- T_CLASS
- T_FUNCTION
- T_INTERFACE
Und fügen Sie einen "Entwurf" Doc-Block kurz vor ihnen hinzu, wenn es noch nicht einen gibt

Das Tool auf einigen ausführen MyClass.php Datei, ich musste zuerst installieren PHP_Beautifier :

pear install --alldeps Php_Beautifier-beta

Laden Sie dann den Filter in das Verzeichnis herunter, in dem ich gearbeitet habe (Natürlich hätte es in das Standardverzeichnis aufnehmen können) :

wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs
cp phpDoc.filter.phpcs phpDoc.filter.php

Und danach habe ich ein neues geschaffen beautifier-1.php Skript (Basierend auf dem, was in dem Blog-Post vorgeschlagen wird, mit dem ich erneut verlinkt habe), welches wird :

Laden Sie den Inhalt meiner MyClass.php Datei
Instanziierung PHP_Beautifier
Fügen Sie einige Filter hinzu, um den Code zu verschönern
Ergänzen Sie die phpDoc Filter haben wir gerade heruntergeladen
Verschönern Sie die Quelle unserer Datei und wiederhole sie an die Standardausgabe.

Der Code des beautifier-1.php Das Skript wird Folgendes mögen:
(Wieder einmal ist der größte Teil eine Kopie des Blog-Posts. Ich habe nur die Kommentare übersetzt und ein paar kleine Dinge geändert)

require_once 'PHP/Beautifier.php';

// Load the content of my source-file, with missing docblocks
$sourcecode = file_get_contents('MyClass.php');

$oToken = new PHP_Beautifier(); 

// The phpDoc.filter.php file is not in the default directory,
// but in the "current" one => we need to add it to the list of
// directories that PHP_Beautifier will search in for filters
$oToken->addFilterDirectory(dirname(__FILE__));

// Adding some nice filters, to format the code
$oToken->addFilter('ArrayNested');  
$oToken->addFilter('Lowercase');        
$oToken->addFilter('IndentStyles', array('style'=>'k&r'));

// Adding the phpDoc filter, asking it to add a license
// at the beginning of the file
$oToken->addFilter('phpDoc', array('license'=>'php'));

// The code is in $sourceCode
// We could also have used the setInputFile method,
// instead of having the code in a variable
$oToken->setInputString($sourcecode);        
$oToken->process();

// And here we get the result, all clean !              
echo $oToken->get();

Beachten Sie, dass ich auch zwei kleine Dinge in den Waffen musste phpDoc.filter.php, um eine Warnung und eine Mitteilung zu vermeiden ...
Der entsprechende Patch kann dort heruntergeladen werden: http://extern.pascal-martin.fr/so/phpdoc.filter-pmn.patch

Nun, wenn wir das laufen beautifier-1.php Skript :

$ php ./beautifier-1.php

Mit einer MyClass.php Datei, die initialisch diesen Code enthält:

class MyClass {
    public function __construct($myString, $myInt) {
        // 
    }

    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...
    }

    protected $_myVar;
}

Hier ist die Art von Ergebnis, die wir erhalten - sobald unsere Datei verschönert ist:

<?php
/**
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 * @category   PHP
 * @package
 * @subpackage Filter
 * @author FirstName LastName <mail>
 * @copyright 2009 FirstName LastName
 * @link
 * @license     http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 */


/**
 * @todo Description of class MyClass
 * @author 
 * @version 
 * @package 
 * @subpackage 
 * @category 
 * @link 
 */
class MyClass {

    /**
     * @todo Description of function __construct
     * @param  $myString 
     * @param  $myInt
     * @return 
     */
    public function __construct($myString, $myInt) {
        //

    }
    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...

    }

    protected $_myVar;
}

Wir können beachten:

Der Lizenzblock am Anfang der Datei
Der Docblock, der auf dem hinzugefügt wurde MyClass Klasse
Der Docblock, der auf dem hinzugefügt wurde __construct Methode
Der docBlock auf der doSomething war bereits in unserem Code vorhanden: Es wurde nicht entfernt.
Dort sind einige @todo Tags ^^

Jetzt ist es natürlich nicht perfekt:

Es dokumentiert nicht all das, was wir es auch wollen könnten
- Zum Beispiel hier dokumentiert es hier nicht protected $_myVar
Es verbessert nicht vorhandene Docblocks
Und es öffnet die Datei in keinem grafischen Editor
- Aber das wäre viel schwieriger, denke ich ...

Aber ich bin mir ziemlich sicher, dass diese Idee als Ausgangspunkt für etwas viel Interessanteres verwendet werden könnte:

Über die Dinge, die nicht dokumentiert werden: Hinzufügen neuer Tags, die erkannt werden, sollte nicht zu schwer sein
- Sie müssen sie nur zu Beginn des Filters zu einer Liste hinzufügen
Die Verbesserung bestehender Docblocks könnte schwieriger sein, ich muss zugeben
Eine schöne Sache ist, dass dies vollautomatisch sein könnte
Mit Eclipse PDT könnte dies möglicherweise als ein festgelegt werden Externes Werkzeug, Also können wir es zumindest aus unserer IDE starten?

Andere Tipps

Da PHPCS bereits erwähnt wurde, habe ich die Reflexions -API eingeworfen, um nach fehlenden Dokblocken zu suchen. Der unten verlinkte Artikel ist ein kurzes Tutorial darüber, wie Sie sich Ihrem Problem angehen können:

http://www.phpriot.com/articles/reflection-api

Da ist auch ein BEAR -Paket PHP_DocBlockGenerator Dadurch können Sie den Dateiseitenblock und die Docblocks für enthält, globale Variablen, Funktionen, Parameter, Klassen, Konstanten, Eigenschaften und Methoden (und andere Dinge).

Php-Tracer-Weaver Kann Instrumentencode und Docblocks mit den Parametertypen generieren, die durch Laufzeitanalyse abgezogen werden.

Du kannst den ... benutzen Code Sniffer Damit PHP Ihren Code gegen einen vordefinierten Satz von Codierungsrichtlinien testen kann. Außerdem werden nach fehlenden Docblocks geprüft und einen Bericht generiert, mit dem Sie die Dateien identifizieren können.

Die 1.4.x-Versionen von PHPDocumentor haben die Option -E-Option (--undocumentEdElements) [1], die dazu führen, dass undokumentierte Elemente als Warnungen auf der fehlern.

Darüber hinaus sieht Php_docBlockGenerator [2] von Pear so aus, als ob er fehlende Docblocks für Sie erzeugen kann.

[1] -- http://manual.phpdoc.org/htmlsmartyconverter/hands/phpdocumentor/tutorial_phpdocumentor.howto.pkg.html#using.command-line.undocumentedElements

[2] -- http://pear.php.net/package/php_docblockgenerator

Wir verwenden CodesNiffer für diese Funktionalität bei der Arbeit mit Standardbirnen- oder Zend -Standards. Sie können nicht ermöglichen, die Dateien im laufenden Fliegen zu bearbeiten, sondern Ihnen auf jeden Fall eine Liste mit Zeilen und Beschreibung, welche Art von DocBlock fehlt.

HTH, JC

Keine Ahnung, ob es sich um Hilfe handelt, aber wenn CodesNiffere auf die Funktionen/Methoden hinweisen kann, kann eine anständige PHP -IDE (ich biete PHPD an) einfach die Phpdoc -Kommentare für jede Funktion inspizieren und inszenieren.

Einfach eingeben /** Über jeder Funktion und drücken @param1, @param1, @return, usw. richtig ausgefüllt, bereit für Ihre zusätzlichen Beschreibungen. Hier ist der erste, den ich versucht habe, um ein Beispiel zu geben:

  /**
  * put your comment here...
  * 
  * @param mixed $url
  * @param mixed $method
  * @param mixed $timeout
  * @param mixed $vars
  * @param mixed $allow_redirects
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

Dies kann leicht optimiert werden:

  /**
  * Retrieves a file using the cURL extension
  * 
  * @param string $url
  * @param string $method
  * @param int $timeout
  * @param array $vars parameters to pass to cURL
  * @param int $allow_redirects boolean choice to follow any redirects $url serves up
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

Nicht gerade eine automatisierte Lösung, aber schnell genug für mich als fauler Entwickler :)

Sie möchten das Problem beim Ausfüllen der "Javadoc" -Typdaten tatsächlich automatisieren?

Das DMS -Software -Reengineering -Toolkit könnte dafür konfiguriert werden.

Es analysiert den Quelltext genau wie Compiler, baut interne Compiler -Strukturen auf, können beliebige Analysen implementieren, diese Strukturen ändern und dann den Quelltext gemäß den Strukturänderungen geändert werden ("hübschprint"). Es bewahrt sogar Kommentare und Formatierung des Originaltextes; Sie können natürlich zusätzliche Kommentare einfügen und sie werden erscheinen, und dies scheint Ihr Hauptziel zu sein. DMS tut dies für viele Sprachen, einschließlich Php

Was Sie tun möchten, ist jede PHP -Datei zu analysieren, jede Klasse/Methode zu suchen, die "Javadoc" -Kommentare zu generieren, die diese Entität sein sollten (Unterschied für Klassen und Methoden, oder?), Und überprüfen Sie dann, dass entsprechende Kommentare tatsächlich in den Compiler -Strukturen. Wenn nicht, setzen Sie sie einfach ein. PrettyPrint das Endergebnis. Da es Zugriff auf die Compiler -Strukturen hat, die den Code darstellen, sollte es nicht schwierig sein, Parameter zu generieren und Informationen zurückzugeben, wie Sie vorgeschlagen haben. Was es nicht kann, ist natürlich Kommentare zur Absicht generieren Zweck; Aber es könnte einen Platzhalter erzeugen, damit Sie später ausfüllen können.

Ich musste kürzlich eine große Automatisierung der Docblock-Fixierung durchführen, hauptsächlich basierend auf der richtigen Antwort über kw-kontextspezifische Änderungen. Es ist ein Hack, aber ich verlinke hier, falls er in Zukunft für andere nützlich ist. Im Wesentlichen führt es eine grundlegende Parsen für Kommentare Block -Token innerhalb von PHP -Verschönern.

https://gist.github.com/israelshirk/408f2656100196e73367

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow