Über PHP-Dokumentationsgenerierungstools

1. Was ist phpDocumentor?

PHPDocumentor ist ein in PHP geschriebenes Tool für PHP-Programme mit Standardanmerkungen, das schnell API-Dokumente mit Querverweisen, Indizierungen und anderen Funktionen generieren kann. Die alte Version heißt phpdoc und wurde in phpDocumentor umbenannt. Gleichzeitig können Dokumente durch den Betrieb im Client-Browser generiert und konvertiert werden PDF, HTML, Es gibt verschiedene Formen von CHM, die sehr praktisch sind.

Wenn PHPDocumentor arbeitet, scannt es den PHP-Quellcode im angegebenen Verzeichnis, scannt die Schlüsselwörter, fängt die Kommentare ab, die analysiert werden müssen, analysiert dann die speziellen Tags in den Kommentaren, generiert eine XML-Datei, Erstellen Sie dann basierend auf der abgeschlossenen Analyse der Klassen- und Modulinformationen entsprechende Indizes, generieren Sie XML-Dateien und verwenden Sie benutzerdefinierte Vorlagen, um Dateien im angegebenen Format für die generierten XML-Dateien auszugeben.

2. phpDocumentor installieren

Wie andere Module unter Pear ist auch die Installation von phpDocumentor in automatische Installation und manuelle Installation unterteilt:

a． Automatisch über Pear installieren

Geben Sie

pear install PhpDocumentor

b ein. Manuelle Installation

Laden Sie die neueste Version von PHPDocumentor (jetzt 1.4.2) unter http://manual.phpdoc.org/ herunter und entpacken Sie den Inhalt.

3． So verwenden Sie PhpDocumentor zum Generieren von Dokumenten

a. Befehlszeilenmethode

Geben Sie im Verzeichnis, in dem sich phpDocumentor befindet,

Php -h

ein Eine detaillierte Parametertabelle, mehrere wichtige Parameter sind wie folgt:

-f Der Name der zu analysierenden Datei, mehrere Dateien durch Kommas getrennt

-d Das zu analysierende Verzeichnis, mehrere Verzeichnisse Durch Kommas getrennt Split

-t Der Speicherpfad des generierten Dokuments

-o Das Ausgabedokumentformat, die Struktur ist Ausgabeformat: Konvertername: Vorlagenverzeichnis.

Zum Beispiel: phpdoc -o HTML:frames:earthli -f test.php -t docs

b Webinterface-Generierung

im neuen phpdoc, außer im Befehl Zusätzlich zum Offline-Generieren von Dokumenten können Sie Dokumente auch im Client-Browser generieren. Die spezifische Methode besteht darin, den Inhalt von PHPDocumentor zunächst im Apache-Verzeichnis abzulegen, damit über den Browser darauf zugegriffen werden kann angezeigt werden:

Klicken Sie auf die Schaltfläche „Dateien“ und wählen Sie die zu verarbeitenden PHP-Dateien oder Ordner aus. Sie können die Verarbeitung bestimmter Dateien auch ignorieren, indem Sie in dieser Schnittstelle „Zu ignorierende Dateien“ angeben.

Klicken Sie dann auf die Schaltfläche „Ausgabe“, um den Speicherpfad und das Format des generierten Dokuments auszuwählen.

Klicken Sie abschließend auf „Erstellen“. phpdocumentor beginnt automatisch mit der Generierung des Dokuments und zeigt den Fortschritt und Status der Generierung an Wird unten angezeigt:

Gesamtdokumentationszeit: 1 Sekunde

Vorgang abgeschlossen!!

Wir können das generierte Dokument anzeigen. Wenn es im PDF-Format vorliegt, lautet der Name standardmäßig „documentation.pdf“.

c. Versuchen Sie es mit phpdocumentor

Im Folgenden nehmen wir phpunit2 in Pear als Beispiel, um zu demonstrieren, wie Sie phpdocumentor zum Generieren von Dokumenten verwenden.

Bestimmen Sie zunächst die Parameter, die wir benötigen:

-d

c:/program files/easyphp5/php/pear/phpunit2

-t

c:/program files/easyphp5/php/phpunit2doc

-o

html:frames:phpedit

Entsprechend den oben genannten Parametern kombinieren wir die folgenden Befehle:

phpdoc -d "c:/program files/easyphp5/php/pear/phpunit2" -t "c:/ program files /easyphp5/php/phpunit2doc" -o "html:frames:phpedit"

Nachdem der obige Befehl ausgeführt wurde, beginnt phpdocumentor, die Quelldatei zu analysieren und Arbeitsinformationen auszugeben.

Nach Abschluss des Befehls wurde unser Dokument generiert. Geben Sie das von uns angegebene Zielverzeichnis ein und öffnen Sie index.html mit einem Browser, um das generierte Dokument anzuzeigen. Die Dokumentoberfläche ist durch den Rahmen in drei Teile unterteilt. Oben links sind Paketinformationen, unten links sind Navigationsinformationen und rechts ist eine detaillierte Informationspräsentationsseite.

Indizes, Funktionslisten, Klassenlisten, Dateilisten und Unterpakete. Durch Klicken auf den Klassenlink oben können wir den Klassenbaum des gesamten Pakets deutlich sehen. Wenn wir auf eine der Klassen klicken, gelangen wir zur Klassenbeschreibungsseite. Die Klassenbeschreibungsseite umfasst hauptsächlich die folgenden Aspekte:

[Beschreibung: Urheberrecht, Autor, Klassenhierarchie usw.], [Klassenvariablen], [Klassenkonstanten], [Methoden], [Geerbte Variablen ] , [Geerbte Methode: eine sehr nützliche Funktion] Wie wäre es mit

, ist es sehr detailliert? Wenn Sie chm generieren möchten, können Sie den vorherigen Parameter -o in „chm:default: default“ ändern, sodass phpdocumentor eine chm-Projektdatei für Sie generiert. Verwenden Sie einfach das chm-Tool von Microsoft, um sie zu kompilieren, um eine verwendbare chm-Datei zu erhalten .

d. Chinesisch verstümmelte Lösung

Wenn der Kommentar auf Chinesisch ist, muss das Sprach-Tag der entsprechenden Vorlage in PHPDocumentor/phpDocumentor/Converters/* von ISO-8859-1 in konvertiert werden utf-8 Ersetzen Sie, andernfalls wird der generierte Code verstümmelt.

4． Fügen Sie Standardkommentare zum PHP-Code hinzu

PHPDocument generiert Dokumente aus den Kommentaren Ihres Quellcodes, sodass der Prozess des Kommentierens Ihres Programms auch der Prozess des Kompilierens der Dokumentation ist. Unter diesem Gesichtspunkt ermutigt PHPdoc Sie, gute Programmiergewohnheiten zu entwickeln und zu versuchen, Spezifikationen und klaren Text zu verwenden, um Ihr Programm zu kommentieren. Gleichzeitig werden einige Probleme der Nichtsynchronisierung zwischen Dokumentvorbereitung und Dokument mehr oder weniger vermieden Updates danach. In phpdocumentor werden Kommentare in Dokumentationskommentare und Nichtdokumentationskommentare unterteilt. Bei den sogenannten Dokumentationskommentaren handelt es sich um mehrzeilige Kommentare, die vor bestimmten Schlüsselwörtern platziert werden. Spezifische Schlüsselwörter beziehen sich auf Schlüsselwörter, die von phpdoc analysiert werden können, wie z. B. Klasse, Variable usw. Einzelheiten finden Sie in Anhang 1. Kommentare, die nicht vor Schlüsselwörtern stehen oder nicht standardisiert sind, werden als Nichtdokumentationskommentare bezeichnet. Diese Kommentare werden von phpdoc nicht analysiert und erscheinen nicht in dem von Ihnen generierten API-Dokument.

So schreiben Sie Dokumentationskommentare:

Alle Dokumentationskommentare bestehen aus /**Der erste mehrzeilige Kommentar heißt DocBlock in phpDocumentor und bezieht sich auf die Hilfeinformationen zu einem bestimmten Schlüsselwort, die von Softwareentwicklern geschrieben wurden, damit andere den spezifischen Zweck dieses Schlüsselworts kennen und wissen können, wie es verwendet wird. PHPDocumentor schreibt vor, dass ein DocBlock die folgenden Informationen enthält:

1. Funktionskurzbeschreibungsbereich

3. Tag-Tag

Dokumentation Kommentare Die erste Zeile ist der Funktionsbeschreibungsbereich. Der Text beschreibt im Allgemeinen kurz die Funktion dieser Klasse, Methode oder Funktion. Der Text der Funktionsbeschreibung wird im Indexbereich des generierten Dokuments angezeigt. Der Inhalt des Funktionsbeschreibungsbereichs kann durch eine Leerzeile oder „.“ abgeschlossen werden. Nach dem Funktionsbeschreibungsbereich folgt eine Leerzeile, gefolgt von einem detaillierten Beschreibungsbereich. Dieser Teil beschreibt hauptsächlich die Funktion und den Zweck Ihrer API im Detail, einschließlich Anwendungsbeispielen, wenn möglich usw. In diesem Abschnitt sollten Sie sich darauf konzentrieren, den gemeinsamen Zweck und die Verwendung Ihrer API-Funktionen oder -Methoden zu klären und anzugeben, ob es sich um plattformübergreifende Informationen handelt. Der übliche Ansatz besteht darin, eine neue Zeile zu beginnen und die Vorsichtsmaßnahmen oder speziellen Informationen zu einer bestimmten Plattform zu schreiben. Diese Informationen sollten ausreichen, damit Ihre Leser die entsprechenden Testinformationen wie Randbedingungen, Parameterbereiche, Haltepunkte usw. schreiben können . Danach gibt es noch eine Leerzeile und dann das Dokument-Tag, das einige technische Informationen angibt, hauptsächlich den Typ des Aufrufparameters, den Rückgabewert und -typ, die Vererbungsbeziehung, verwandte Methoden/Funktionen usw.

Ausführliche Informationen zu Dokument-Tags finden Sie unter -- Dokument-Tags. Tags wie können auch in Dokumentkommentaren verwendet werden. Weitere Informationen finden Sie in Anhang 2.

Das Folgende ist ein Beispiel für einen Dokumentkommentar

/**

* Funktion add, die die Addition zweier Zahlen implementiert

*

* Eine einfache Additionsberechnung, die Funktion akzeptiert zwei Zahlen a und b und gibt ihre Summe c zurück

*

* @param int addend

* @param int summand

* @return integer

*/

Funktion Add($a, $ b)

{

return $a $b;

}

Das generierte Dokument sieht wie folgt aus:

Hinzufügen

integer Add( int $a, int $b)

[Zeile 45]

Funktion add zum Implementieren der Addition zweier Zahlen

Konstanten Eine einfache Additionsberechnung: Die Funktion akzeptiert zwei Zahlen a und b und gibt deren Summe c zurück

Parameter

? int $a – der Summand

? int $b – die Summe hinzugefügt werden Anzahl

5. Dokument-Tag:

Der Anwendungsbereich des Dokument-Tags bezieht sich auf die Schlüsselwörter oder andere Dokument-Tags, die mit dem Tag geändert werden können. Alle Dokumentations-Tags beginnen in jeder Zeile mit @ nach *. Wenn die @-Markierung in der Mitte eines Absatzes erscheint, wird die Markierung als normaler Inhalt behandelt und ignoriert.

@access

Verwendungsbereich: Klasse, Funktion, Variable, Definition, Modul

Dieses Tag wird verwendet, um die Zugriffsberechtigung von Schlüsselwörtern anzugeben: privat, öffentlich oder geschützt

@author

Verwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, Verwendung

Geben Sie den Autor an

@copyright

Anwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, Verwendung

Copyright-Informationen angeben

@deprecated

Verwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, constent , global, include

Zeigt unbenutzte oder veraltete Schlüsselwörter an

@example

Dieses Tag wird verwendet, um einen Teil des Dateiinhalts zu analysieren und hervorzuheben. PHPDOC versucht, den Dateiinhalt aus dem durch dieses Tag angegebenen Dateipfad zu lesen

@const

Verwendungsbereich: define

wird verwendet, um die Konstante von define in PHP anzugeben

@final

Verwendungsbereich: Klasse, Funktion, var

Gibt an, dass das Schlüsselwort eine endgültige Klasse, Methode, ein Attribut ist und die Ableitung und Änderung verbietet.

@filesource

ähnelt Beispiel, außer dass dieses Tag den Inhalt der aktuell analysierten PHP-Datei direkt liest und anzeigt.

@global

Gibt die globale Variable an, auf die in dieser Funktion verwiesen wird

@ingore

wird verwendet, um das angegebene Schlüsselwort im Dokument zu ignorieren

@license

entspricht im HTML-Tag, zuerst ist die URL, dann der anzuzeigende Inhalt

Zum Beispiel Baidu

kann als @license http://www.baidu.com Baidu

@link

geschrieben werden ähnelt der Lizenz

Aber Sie können auch über einen Link auf ein beliebiges Schlüsselwort im Dokument verweisen

@name

Gibt einen Alias ​​für das Schlüsselwort an.

@package

Verwendungsbereich: Definieren, Funktion, Include auf Seitenebene

Klasse, Variable, Methoden auf Klassenebene

werden zur logischen Anwendung verwendet Ein oder mehrere Schlüsselwörter werden zu einer Gruppe zusammengefasst.

@abstrcut

Gibt an, dass die aktuelle Klasse eine abstrakte Klasse ist

@param

Gibt die Parameter einer Funktion an

@ return

Gibt den Rückgabezeiger einer Methode oder Funktion an

@static

Gibt an, dass das Schlüsselwort statisch ist.

@var

Geben Sie den Variablentyp an

@version

Geben Sie die Versionsinformationen an

@todo

Geben Sie an, ob Verbesserungen oder mangelnde Implementierung erfolgen sollten

@throws

Zeigt die Fehlerausnahmen an, die diese Funktion möglicherweise auslöst, und die Extremsituationen

Wie oben erwähnt, markiert das normale Dokument-Markup es muss am Anfang jeder Zeile mit @ gekennzeichnet werden. Darüber hinaus gibt es auch ein Tag namens Inline-Tag, das durch {@} dargestellt wird, einschließlich des folgenden:

{@link}

Die Verwendung ist die gleiche wie bei @link

{@source}

Den Inhalt einer Funktion oder Methode anzeigen

6. Einige Kommentarspezifikationen

a. Kommentare müssen in der Form

/**

* XXXXXXX

*/

b vorliegen Variablenfunktionen müssen mit glboal markiert sein.

c. Für Variablen müssen ihre Typen (int, string, bool...) mit var

d gekennzeichnet sein. Funktionen müssen ihre Parameter und Rückgabewerte über param und return angeben Markierungen

e. Ignorieren Sie bei Schlüsselwörtern, die zweimal oder öfter vorkommen, die überflüssigen Markierungen durch Ingore und behalten Sie nur eine bei

f. Verwenden Sie bei Aufrufen anderer Funktionen oder Klassen Link oder andere Tags den entsprechenden Abschnitt, um das Lesen des Dokuments zu erleichtern.

g. Verwenden Sie bei Bedarf Nicht-Dokumentationskommentare, um die Lesbarkeit des Codes zu verbessern.

h. Halten Sie den beschreibenden Inhalt prägnant und auf den Punkt und verwenden Sie nach Möglichkeit Phrasen statt Sätze.

i. Globale Variablen, statische Variablen und Konstanten müssen mit entsprechenden Tags markiert werden

7. Zusammenfassung

Dokumentation zu schreiben ist eine mühsame, aber notwendige Aufgabe Dokumente auf API-Ebene bedeuten viel wiederholte Arbeit und Schwierigkeiten bei der Aufrechterhaltung der Konsistenz. Was wir hier jedem empfehlen möchten, ist das Dokumenttool, das die PHP5-Syntaxanalyse unterstützt – phpDocumentor. phpDocumentor ist ein sehr leistungsfähiges Tool zur automatischen Dokumentgenerierung. Es kann uns dabei helfen, standardisierte Kommentare zu schreiben und leicht verständliche, klar strukturierte Dokumente zu generieren, was für unsere Code-Upgrades, Wartung, Übergabe usw. sehr hilfreich ist. Mit phpDocumentor können Sie nicht nur automatisch Funktions- und Methodendefinitionen aus dem Code extrahieren, sondern auch automatisch die Beziehung zwischen verschiedenen Klassen verarbeiten und entsprechend einen Klassenbaum generieren. Sie können das Dokument auch im HTML-, CHM- oder PDF-Format generieren. Mit phpDocumentor wird die Dokumentationsarbeit viel einfacher. Eine detailliertere Beschreibung von phpDocumentor finden Sie auf der offiziellen Website: http://manual.phpdoc.org/.