Einführung in Phpdoc

Kernpunkte

• PHPDOC (PHPDocumentor) ist ein leistungsstarkes Tool, mit dem Entwicklern Codedokumente über spezielle Formatanmerkungen schreiben können. Es kann Dokumente in mehreren Formaten wie HTML, PDF und CHM generieren, die über eine Webschnittstelle oder eine Befehlszeilenschnittstelle extrahiert werden können.
• PHPDOC verwendet DocBlocks (Multi-Line-C-Style-Kommentare), um Codeblöcke zu dokumentieren. Docblocks enthält drei optionale Teile: eine kurze Beschreibung, eine detaillierte Beschreibung und ein Tag. Das Tag beginnt mit dem Symbol @, das zusätzliche Informationen zum Code angibt.
• Das PHPDOC -Paket wird verwendet, um relevante Codeelemente im generierten Dokument zu gruppieren. Sie können Pakete für Dateien und Klassen angeben, die die Tags @package und @subpackage in der Dateiebene oder im Dokument auf Dateiebene oder Klassenebene aufweisen.
• PHPDOC kann Dokumente für verschiedene Codeelemente schreiben, einschließlich Dateien, Klassen, Funktionen und Methoden, Klasseneigenschaften, globale Variablen, include()/require() und define(). Diese Elemente können bestimmte gemeinsame Tags verwenden, aber jedes hat ein bestimmtes Tag.
Das Befehlszeilen-Tool von
• PHPDOC wird verwendet, um benutzerfreundliche Dokumente basierend auf dem geschriebenen PHP-Code zu generieren. Dieses Tool bietet eine Vielzahl von Dokumentformaten. Für Benutzer, die mit der Befehlszeilenschnittstelle nicht vertraut sind, bietet PHPDOC auch eine Weboberfläche.

Code lesen, das von anderen geschrieben wurde (wer hat ihn nicht erlebt?), Ist eine schwierige Aufgabe. Der chaotische "Pasta-Code" wird mit einer großen Anzahl seltsam benannter Variablen gemischt, wodurch er schwindelig ist. Erwartet diese Funktion Strings oder Arrays? Ist diese variablen Ganzzahlen oder Objekte? Nach unzähligen Stunden Codeverfolgung und dem Versuch, die Funktionalität jedes Teils zu verstehen, ist es üblich, den gesamten Code von Grund auf neu zu schreiben und neu zu schreiben - es ist eine Verschwendung Ihrer kostbaren Zeit. PHPDOC (der kurze Name für PHPDocumentor) ist ein leistungsstarkes Tool, mit dem Sie Codendokumente mit Kommentaren in speziellen Formaten problemlos schreiben können. Dokumente sind nicht nur im Quellcode verfügbar, sondern auch professionelle Dokumente, die über die Webschnittstelle oder die Befehlszeilenschnittstelle extrahiert werden. Das Ergebnis kann in einer Vielzahl von Formaten wie HTML, PDF und CHM vorliegen. Darüber hinaus können viele IDEs, die Code -Abschluss bieten, PHPDOC -Kommentare analysieren und praktische Funktionen wie Typ -Eingabeaufforderungen bereitstellen. Durch die Verwendung von PHPDOC können Sie es anderen (und sich selbst) erleichtern, Ihren Code zu verstehen - selbst nach Wochen, Monaten oder sogar Jahren nach dem Schreiben. Der einfachste Weg, PHPDOC zu installieren, besteht darin, Birnen zu verwenden. Natürlich muss Birne installiert werden, bevor Sie dies tun. Wenn Sie keine Birne installiert haben, befolgen Sie die Anweisungen unter pear.php.net/manual/en/installation.php. In diesem Artikel werde ich Ihnen zeigen, wie Sie von Anfang bis Ende mit PHPDOC schöne und benutzerfreundliche Dokumente generieren.

docBlocks

docBlock ist ein Multi-Line-C-Style-Kommentar, mit dem Dokumente für Codeblöcke geschrieben werden. Es beginnt mit /** und jede Zeile hat einen Sternchen. Hier ist ein Beispiel:

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

docblocks enthält drei Teile: eine kurze Beschreibung, eine detaillierte Beschreibung und ein Etikett. Alle drei Teile sind optional. Eine kurze Beschreibung ist eine kurze Beschreibung, die mit einer neuen Linie oder einer neuen Zeit endet. Die analytische Routine von PHPDOC ist intelligent. Eine detaillierte Beschreibung ist der Hauptinhalt eines Dokuments. Sowohl detaillierte als auch kurze Beschreibungen können bestimmte HTML -Elemente für die Formatierung enthalten. Nicht unterstützte HTML -Tags werden als einfacher Text angezeigt. PHPDOC kann Dokumente in mehreren Formaten generieren, sodass HTML -Tags nicht unbedingt wie in HTML -Dateien ausführen. Wenn Sie HTML -Tags als Text anzeigen müssen, verwenden Sie Doppelklammern. Zum Beispiel:

<?php
/**
 * 这里是斜体标签的示例： >Hello, world!>
 */

Der Tag -Abschnitt von

docBlock enthält eine beliebige Anzahl von speziellen Tags, die durch das Symbol @ dargestellt werden. Tags werden verwendet, um zusätzliche Informationen anzugeben, z. B. die erwarteten Parameter und deren Typen. Die meisten Tags müssen in eigenen Reihen sein, aber einige Tags können eingefügt werden. Inline -Tags sind in lockigen Klammern eingeschlossen und können in detaillierten Beschreibungen und kurzen Beschreibungen erscheinen. Eine vollständige Liste von Tags finden Sie in der entsprechenden PHPDOC -Dokumentation. Wenn Sie eine Zeile benötigen, um mit dem Symbol @ zu beginnen, aber nicht als Etikett interpretieren möchten, können Sie ihm mit einem Rückgang entkommen. PHPDOC identifiziert und analysiert die Textliste automatisch in der detaillierten Beschreibung und der kurzen Beschreibung. Es wird jedoch keine verschachtelten Listen korrekt analysiert. Wenn Sie verschachtelte Listen verwenden möchten, verwenden Sie HTML -Tags. Hier ist ein Beispiel, um zu veranschaulichen, was ich meine:

<?php
/**
 * 使用列表的示例
 *
 * PhpDoc 将正确解析此列表：
 * - 项目 #1
 * - 项目 #2
 * - 项目 #3
 *
 * 但不是这个列表：
 * - 项目 1
 *   - 项目 1.1
 *   - 项目 1.2
 * - 项目 2
 *
 * 请改用此方法创建嵌套列表：
 * 

*

项目 1

*

*

项目 1.1

*

项目 1.2

* *

项目 2

* */

(Der folgende Inhalt wird aufgrund von Platzbeschränkungen und beibehaltenen Schlüsselinformationen kurz zusammengefasst)

Bag

Das PHPDOC -Paket wird verwendet, um relevante Codeelemente im generierten Dokument zu gruppieren. Sie können Pakete für Dateien und Klassen angeben, die Code enthalten, um diese Pakete zu erben. Um ein Paket anzugeben, legen Sie das @package -Tag in der Dateiebene oder Klassenebene auf Docblock. (Docblocks auf Dateiebene und Klassenebene werden im nächsten Abschnitt weiter erläutert). Packungsnamen können Buchstaben, Zahlen, Dash, Unterstrich und Quadratklammern enthalten ("[" und "]"). Hier ist ein Beispiel dafür, wie ein Dateipaket definiert wird:

<?php
/**
 * 这是一个文件级 DocBlock
 *
 * @package Some_Package
 */

Wenn Sie über mehrere Paket- und Unterpackungsstufen verfügen, können Sie das @subpackage -Tag zum Definieren von Unterpackungen verwenden. Hier ist ein Beispiel:

<?php
/**
 * 这是一个类级 DocBlock
 *
 * @package    Some_Package
 * @subpackage Other
 */
class SomeClass {
}

Wenn die Datei oder Klasse kein Paket angeben, wird sie auf das Standardpaket "Standard" festgelegt. Sie können andere Pakete angeben, die standardmäßig über die Befehlszeilenoption -dn verwendet werden können.

Welche Dokumente können geschrieben werden?

Nicht alle Codeelemente können mit DocBlocks geschrieben werden. Hier ist eine Liste von Codeelementen, die im Dokument geschrieben werden können:

• Datei
• Kategorie
• Funktionen und Methoden
• Klasse Attribute
• globale Variablen
• include()/require()
• define()

Alle diese Elemente können bestimmte gängige Beschriftungen verwenden, aber jedes Element verfügt über eine Beschriftung, die für dieses Element spezifisch ist. Ich werde einige Elemente und Tags behandeln, die normalerweise verwendet werden, um Dokumentationen für sie zu schreiben.

(Die Dokumentationsbeispiele für Dateien, Klassen, Funktionen und Methoden sind kurz. Nur wichtige Tag -Beschreibungen werden beibehalten)

Dokument

generieren

Nach dem Schreiben der Dokumentation für Ihren PHP-Code müssen Sie benutzerfreundliche Dokumente daraus generieren. Führen Sie dazu das PHPDOC -Befehlszeilenwerkzeug aus.

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

(Die Beschreibung der Befehlszeilenparameter ist kurz)

Für Benutzer, die mit der Befehlszeilenschnittstelle nicht vertraut sind, bietet PHPDOC auch eine Weboberfläche. In diesem Dokument werden es nicht ausführlich erörtert, aber Sie können mehr auf der offiziellen Website von PHPDOC, Phpdoc.org, erfahren.

Zusammenfassung

In diesem Artikel stelle ich Ihnen PHPDOC und seine vielen leistungsstarken Funktionen vor. Ich habe den Zweck von Docblocks und seinen Komponenten erklärt. Ich empfehle Ihnen dringend, PHPDOC in Ihrem eigenen Projekt zu verwenden, auch wenn nur die Dokumentation für die wichtigsten Teile geschrieben wird. Es ist sehr einfach und kann Sie und Ihre Kollegen unzählige Stunden Spannung und Schmerzen retten.

(Der FAQ -Abschnitt wird kurz sein, die Kernfragen und kurze Antworten beibehalten)

Das obige ist der detaillierte Inhalt vonEinführung in Phpdoc. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!