PHPDocumentor ist ein in PHP geschriebenes Tool für PHP-Programme mit Standardanmerkungen, mit dem schnell API-Dokumente mit Querverweisen, Indizierungen und anderen Funktionen generiert werden können. Die alte Version ist phpdoc.
1. Was ist phpDocumentor?
PHPDocumentor ist ein in PHP geschriebenes Tool für PHP-Programme mit Standardanmerkungen, mit dem schnell API-Dokumente mit Querverweisen, Indizierungen und anderen Funktionen generiert werden können. 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 funktioniert, 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 und basiert dann auf den Informationen von Die analysierten Klassen und Module erstellen entsprechende Indizes, generieren XML-Dateien und verwenden benutzerdefinierte Vorlagen, um Dateien im angegebenen Format für die generierten XML-Dateien auszugeben.
2. Installieren Sie phpDocumentor
Wie andere Module unter Pear ist auch die Installation von phpDocumentor in zwei Methoden unterteilt: automatische Installation und manuelle Installation. Beide Methoden sind sehr praktisch:
A. Automatisch über Pear installieren und in die Befehlszeile eingeben
Birne PHPDocumentor installieren
B. Installieren Sie manuell die neueste Version von PhpDocumentor (jetzt 1.4.0) unter http://manual.phpdoc.org/ und entpacken Sie den Inhalt.
3． So verwenden Sie PHPDocumentor zum Generieren der Dokumentationsbefehlszeile:
Geben Sie im Verzeichnis, in dem sich phpDocumentor befindet, Folgendes ein:
PHP-h
Sie erhalten eine detaillierte Parameterliste mit einigen wichtigen Parametern:
-f Der Name der zu analysierenden Datei, mehrere Dateien durch Kommas getrennt
-d Zu analysierendes Verzeichnis, mehrere Verzeichnisse durch Kommas getrennt
-t 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
Die Weboberfläche wird im neuen PHPDoc generiert. Zusätzlich zum Generieren von Dokumenten in der Befehlszeile können Sie Dokumente auch im Client-Browser generieren. Die spezifische Methode besteht darin, den Inhalt von PhpDocumentor zunächst im Apache-Verzeichnis zu platzieren Wenn Sie über den Browser darauf zugreifen, wird nach dem Zugriff die folgende Oberfläche angezeigt:
Klicken Sie auf die Schaltfläche „Dateien“, um die zu verarbeitenden PHP-Dateien oder Ordner auszuwählen. 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“, und phpdocumentor beginnt automatisch mit der Generierung von Dokumenten. Der Fortschritt und der Status der Generierung werden unten angezeigt.
Gesamtdokumentationszeit: 1 Sekunde
Erledigt
Vorgang abgeschlossen!!
Anschließend können wir das generierte Dokument anzeigen. Wenn es im PDF-Format vorliegt, lautet der Name standardmäßig „documentation.pdf“.
4. Fügen Sie Standardkommentare zum PHP-Code hinzu
PHPDocument generiert Dokumente aus Kommentaren in Ihrem Quellcode, 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 stehen. 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 im von Ihnen generierten API-Text.
3.2 So schreiben Sie Dokumentationskommentare:
Alle Dokumentationskommentare sind mehrzeilige Kommentare, die mit /** beginnen und in phpDocumentor auf die Hilfeinformationen zu einem bestimmten Schlüsselwort verweisen, damit andere dies erfahren können Der spezifische Zweck von Schlüsselwörtern und wie man sie verwendet. PHPDocumentor gibt an, dass ein DocBlock die folgenden Informationen enthält:
1. Bereich mit Kurzbeschreibung der Funktion
2. Detaillierter Beschreibungsbereich
3. Markieren
Die erste Zeile des Dokumentationskommentars ist der Funktionsbeschreibungsbereich. Der Text erklärt 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 abgeschlossen werden, gefolgt von einem detaillierten Beschreibungsbereich. Sie können auch Anwendungsbeispiele usw. verwenden. In diesem Abschnitt sollten Sie sich auf die Klärung des allgemeinen Zwecks und der Verwendung Ihrer API-Funktionen oder -Methoden konzentrieren und angeben, ob es sich um plattformübergreifende Informationen handelt (sofern es sich um plattformbezogene Informationen handelt). Der übliche Ansatz besteht darin, eine neue Zeile zu beginnen und dann die Vorsichtsmaßnahmen oder speziellen Informationen zu einer bestimmten Plattform zu schreiben. Diese Informationen sollten ausreichen, damit Ihre Leser entsprechende Testinformationen wie Randbedingungen, Parameterbereiche, Haltepunkte usw. schreiben können.
Danach gibt es auch 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.
Einzelheiten zur Dokumentenkennzeichnung finden Sie in Abschnitt 4: Dokumentenkennzeichnung.
Tags wie <b> <code> können auch in Dokumentkommentaren verwendet werden. Weitere Informationen finden Sie in Anhang 2.
Das Folgende ist ein Beispiel für einen Dokumentationskommentar
/**
* Funktion add, implementiert die Addition zweier Zahlen
*
* Eine einfache Additionsrechnung. Die Funktion akzeptiert zwei Zahlen a und b und gibt deren Summe c zurück
*
* @param int addend
* @param int Summand
* @return Ganzzahl
*/
Funktion Add($a, $b) {
return $a+$b;
}
Das generierte Dokument sieht wie folgt aus:
Hinzufügen
Ganzzahl Add(int $a, int $b)
[Zeile 45]
Funktion add, implementiert die Addition zweier Zahlen
Constants ist eine einfache Additionsrechnung. Die Funktion akzeptiert zwei Zahlen a und b und gibt deren Summe c zurück.
Parameter
• int $a – Summand
• int $b – Summand
5. Dokument-Tags:
Der Verwendungsbereich eines 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 mit @ nach dem * in jeder Zeile. Wenn die @-Markierung in der Mitte eines Absatzes erscheint, wird die Markierung als normaler Inhalt behandelt und ignoriert.
@Zugang
Anwendungsbereich: Klasse, Funktion, Variable, Definition, Modul
Dieses Tag wird verwendet, um die Zugriffsrechte des Schlüsselworts anzugeben: privat, öffentlich oder geschützt
@Autor
Geben Sie den Autor an
@Copyright
Anwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, Verwendung
Geben Sie Copyright-Informationen an
@veraltet
Anwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, Inhalt, global, einschließen
Geben Sie nicht verwendete oder veraltete Schlüsselwörter an
@Beispiel
Dieses Tag wird verwendet, um einen Teil des Dateiinhalts zu analysieren und hervorzuheben. PHPdoc wird versuchen, den Dateiinhalt aus dem durch dieses Tag angegebenen Dateipfad zu lesen.
@const
Anwendungsbereich: definieren
Wird verwendet, um die in PHP definierten Konstanten anzugeben
@Finale
Anwendungsbereich: Klasse, Funktion, Var
Gibt an, dass das Schlüsselwort eine endgültige Klasse, Methode oder ein Attribut ist und nicht abgeleitet oder geändert werden darf.
@filesource
Ähnlich wie bei Beispiel, außer dass dieses Tag den Inhalt der aktuell analysierten PHP-Datei direkt liest und anzeigt.
@global
Gibt die globalen Variablen an, auf die in dieser Funktion verwiesen wird
@ingore
Wird verwendet, um bestimmte Schlüsselwörter im Dokument zu ignorieren
@Lizenz
Äquivalent zu <a> im HTML-Tag, zuerst die URL und dann der anzuzeigende Inhalt, z. B. <a href=“http://www.baidu.com“>Baidu</a>
Sie können @license http://www.baidu.com Baidu schreiben
@Link
ähnlich wie eine Lizenz
Sie können aber auch über einen Link auf ein beliebiges Schlüsselwort im Dokument verweisen
@Name
Geben Sie einen Alias für das Schlüsselwort an.
@Paket
Anwendungsbereich: Seitenebene -> Definieren, Funktion, Einschließen
Klassenebene -> Klasse, Variable, Methoden
Wird verwendet, um ein oder mehrere Schlüsselwörter logisch zu einer Gruppe zusammenzufassen.
@abstrcut
Gibt an, dass die aktuelle Klasse eine abstrakte Klasse ist
@param
Geben Sie die Parameter einer Funktion an
@zurückkehren
Gibt den Rückgabezeiger einer Methode oder Funktion an
@statisch
Zeigt an, dass das Schlüsselwort statisch ist.
@var
Geben Sie den Variablentyp an
@Version
Geben Sie Versionsinformationen an
@todo
Geben Sie Bereiche an, die verbessert oder nicht umgesetzt werden sollten
@throws
Gibt die Fehlerausnahme an, die diese Funktion auslösen kann. Wie oben erwähnt, müssen normale Dokument-Tags am Anfang jeder Zeile mit @ markiert werden. Darüber hinaus gibt es auch ein Tag namens Inline-Tag, das {@} bedeutet , insbesondere Folgendes:
{@link }
Die Verwendung ist die gleiche wie bei @link
{@Quelle }
Zeigt den Inhalt einer Funktion oder Methode an
6． Einige Anmerkungsspezifikationen
a. Der Kommentar muss sein
/**
* XXXXXXX
*/
bilden
b. Für Funktionen, die auf globale Variablen verweisen, muss das glboal-Tag verwendet werden.
c. Für Variablen muss ihr Typ mit var (int, string, bool...) gekennzeichnet sein.
d. Die Funktion muss ihre Parameter und ihren Rückgabewert über Parameter- und Rückgabe-Tags angeben
e. Ignorieren Sie bei Schlüsselwörtern, die zweimal oder öfter vorkommen, die überflüssigen Schlüsselwörter durch Ingore und behalten Sie nur eines bei.
f. Wenn andere Funktionen oder Klassen aufgerufen werden, sollten Link- oder andere Tags verwendet werden, um auf den entsprechenden Teil zu verweisen, um das Lesen des Dokuments zu erleichtern.
g. Verwenden Sie bei Bedarf nicht dokumentarische Kommentare, 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 deklariert werden
7. Zusammenfassung
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.
Eine detailliertere Beschreibung von phpDocumentor finden Sie auf der offiziellen Website
http://manual.phpdoc.org/View
8. Anhang Anhang 1:
Von phpdoc erkannte Schlüsselwörter:
Enthalten
Erfordern
include_once
require_once
definieren
Funktion
global
Klasse
Anhang 2
Tags, die in Dokumenten verwendet werden können
<b>
<Code>
<br>
<kdb>
<li>
<pre>
<ul>
<samp>
<var>
Anhang 3:
Ein Stück PHP-Code mit kanonischen Kommentaren:
<?php
/**
* Beispieldatei 2, phpDocumentor Quickstart
*
* Diese Datei zeigt die umfangreichen Informationen, die darin enthalten sein können
* In-Code-Dokumentation durch DocBlocks und Tags.
* @Autor Greg Beaver < [email protected] >
* @Version 1.0
* @Paketbeispiel
*/
// Beispieldatei Nr. 1
/**
* Dummy-Include-Wert, um die Parsing-Leistung von phpDocumentor zu demonstrieren
*/
include_once 'sample3.php';
/**
* Spezielle globale Variablendeklaration DocBlock
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*Konstanten
*/
/**
* erste Konstante
*/
define('testing', 6);
/**
* zweite Konstante
*/
define('anotherconstant', strlen('hello'));
/**
* Ein Beispielfunktions-Docblock
* @global string dokumentiert die Tatsache, dass diese Funktion $_myvar verwendet
* @staticvar integer $staticvar Dies ist tatsächlich das, was zurückgegeben wird
* @param string $param1 zu deklarierender Name
* @param string $param2 Wert des Namens
* @return Ganzzahl
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
/**
* Die erste Beispielklasse, diese befindet sich im selben Paket wie die
*prozedurales Zeug am Anfang der Datei
* @Paketbeispiel
* @subpackage-Klassen
*/
Klasse myclass {
/**
* Eine Beispiel-Privatvariable, diese kann mit --parseprivate ausgeblendet werden
*Option
* @accessprivate
* @var Ganzzahl|Zeichenfolge
*/
var $firstvar = 6;
/**
* @link http://www.example.com Beispiellink
* @see myclass()
* @verwendet Tests, eine andere Konstante
* @var-Array
*/
var $secondvar =
Array(
'Zeug' =>
Array(
6,
17,
'Gürteltier'
),
testen => eine andere Konstante
);
/**
* Konstruktor richtet {@link $firstvar} ein
*/
Funktion myclass() {
$this->firstvar = 7;
}
/**
* Gibt ein Ding basierend auf $paramie zurück
* @param boolean $paramie
* @return integer|babyclass
*/
Funktion parentfunc($paramie) {
if ($paramie) {
Rückkehr 6;
} anders {
neue Babyklasse zurückgeben;
}
}
}
/**
* @Paketbeispiel1
*/
Klasse babyclass erweitert myclass {
/**
* Die Antwort auf das Leben, das Universum und alles
* @var Ganzzahl
*/
var $secondvar = 42;
/**
* Konfigurationswerte
* @var-Array
*/
var $thirdvar;
/**
* Ruft den übergeordneten Konstruktor auf und erhöht dann {@link $firstvar}
*/
Funktion babyclass() {
parent::myclass();
$this->firstvar++;
}
/**
* Dies gibt immer eine myclass zurück
* @param ignorierte $paramie
* @return myclass
*/
Funktion parentfunc($paramie) {
gib neue myclass zurück;
}
}
?>