PDP-Dokumentcode-Kommentarspezifikation

1. Was ist phpDocumentor?<br>PHPDocumentor ist ein in PHP geschriebenes Tool, das schnell API-Dokumente mit Querverweisen, Indizierung 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. <br>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 darauf Erstellen Sie anhand der analysierten Klassen und Modulinformationen den entsprechenden Index und generieren Sie XML-Dateien. Verwenden Sie für die generierten XML-Dateien benutzerdefinierte Vorlagen, um Dateien im angegebenen Format auszugeben. <br>2. phpDocumentor installieren<br> Wie andere Module unter Pear ist auch die Installation von phpDocumentor in zwei Methoden unterteilt: automatische Installation und manuelle Installation: <br>a. Automatisch über Pear installieren<br>Geben Sie <br>pear install PhpDocumentor<br>b ein. Manuelle Installation<br>Laden Sie die neueste Version von PHPDocumentor (jetzt 1.4.0) unter http://manual.phpdoc.org/ herunter und entpacken Sie den Inhalt. <br>3． So verwenden Sie PhpDocumentor zum Generieren von Dokumenten <br>Befehlszeilenmethode: <br>Geben Sie in dem Verzeichnis, in dem sich phpDocumentor befindet, <br>Php –h<br> ein, um eine detaillierte Parameterliste zu erhalten, von der einige wichtige Parameter wie folgt lauten : <br> -f Zu analysierender Dateiname, mehrere Dateien durch Kommas getrennt <br> -d Zu analysierendes Verzeichnis, mehrere Verzeichnisse durch Kommas getrennt <br>-t Speicherpfad des generierten Dokuments <br>-o Ausgabedokument Format, die Struktur ist Ausgabeformat: Konvertername: Vorlagenverzeichnis. <br>Zum Beispiel: phpdoc -o HTML:frames:earthli -f test.php -t docs<br>Webschnittstellen-Generierung<br>Im neuen phpdoc können Sie zusätzlich zum Generieren von Dokumenten über die Befehlszeile auch Dokumente generieren Dokumente auf dem Client Um Dokumente durch Betrieb im Browser zu generieren, besteht die spezifische Methode darin, den Inhalt von PhpDocumentor zunächst im Apache-Verzeichnis abzulegen, damit über den Browser darauf zugegriffen werden kann. Nach dem Zugriff wird die folgende Schnittstelle angezeigt: <br> Klicken Sie auf die Schaltfläche „Dateien“ und wählen Sie die zu verarbeitenden PHP-Dateien aus. Sie können die Verarbeitung bestimmter Dateien auch ignorieren, indem Sie unter dieser Schnittstelle „Zu ignorierende Dateien“ angeben. <br>Klicken Sie dann auf die Schaltfläche „Ausgabe“, um den Speicherpfad und das Format des generierten Dokuments auszuwählen. <br>Klicken Sie abschließend auf „Erstellen“, und phpdocumentor beginnt automatisch mit der Generierung des Dokuments. Der Fortschritt und der Status der Generierung werden unten angezeigt. Bei Erfolg: <br>Gesamtdokumentationszeit: 1 Sekunde<br>fertig<br>Vorgang abgeschlossen!!<br>Dann können wir das generierte Dokument anzeigen. Wenn es im PDF-Format vorliegt, lautet der Name standardmäßig „documentation.pdf“. <br>4． Fügen Sie standardisierte Kommentare zum PHP-Code hinzu <br>PHPDocument generiert Dokumente aus den Kommentaren Ihres Quellcodes, sodass der Prozess des Kommentierens Ihres Programms auch der Prozess des Kompilierens der Dokumentation ist. <br>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 wird die asynchrone Entwicklung von Dokumenten und Dokumentaktualisierungen im Nachhinein mehr oder weniger vermieden. Einige Fragen. <br> In phpdocumentor werden Kommentare in Dokumentationskommentare und Nichtdokumentationskommentare unterteilt. <br>Die sogenannten Dokumentationskommentare sind 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. <br> 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. <br>3.2 So schreiben Sie Dokumentationskommentare: <br> Alle Dokumentationskommentare sind mehrzeilige Kommentare, die mit /** beginnen und in phpDocumentor als Schlüsselkommentar bezeichnet werden. Die Hilfeinformationen Durch die Verwendung des Schlüsselworts können andere den spezifischen Zweck dieses Schlüsselworts und seine Verwendung erfahren. PHPDocumentor legt fest, dass ein DocBlock die folgenden Informationen enthält: <br>1. Funktionskurzbeschreibungsbereich <br> 2. Detaillierter Beschreibungsbereich <br>3 Mark-Tag <br> Die erste Zeile des Dokumentationskommentars ist der Funktionsbeschreibungsbereich. und der Text lautet im Allgemeinen: Beschreiben Sie kurz die Funktion dieser Klasse, Methode oder Funktion. Der Text der kurzen Funktionsbeschreibung wird im Bereich index im generierten Dokument angezeigt. Der Inhalt des Funktionsbeschreibungsbereichs kann durch eine Leerzeile abgeschlossen werden oder <br>Nach dem Funktionsbeschreibungsbereich folgt eine detaillierte Beschreibung. Wenn möglich, können Sie auch Anwendungsbeispiele usw. nennen. 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 Hinweise oder spezielle Informationen zu einer bestimmten Plattform zu schreiben. Diese Informationen sollten ausreichen, damit Ihre Leser entsprechende Testinformationen, wie z. B. Randbedingungen, Parameter, schreiben können Bereiche, Haltepunkte usw.Nach <br> 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. <br> Einzelheiten zu Dokument-Tags finden Sie in Abschnitt 4: Dokument-Tags. <br>Sie können in Dokumentkommentaren auch Tags wie verwenden. <br>Das Folgende ist ein Beispiel für einen Dokumentationskommentar<br>/**<br>* Funktion add, implementiert die Addition zweier Zahlen <br>*<br>* Eine einfache Additionsberechnung, die Funktion akzeptiert zwei Zahlen a und b und gibt deren Summe c zurück<br>* <br>* @ param int addend<br>* @param int addend<br>* @return integer <br>*/<br>Funktion Add($a, $b)<br>{<br> return $a $b;<br>} <br>Das generierte Dokument sieht wie folgt aus: <br>Add<br>integer Add( int $a, int $b) <br>[Zeile 45]<br>Funktion add, um die Addition zweier Zahlen zu implementieren<br>Konstanten A einfach Für die Additionsberechnung akzeptiert die Funktion zwei Zahlen a und b und gibt deren Summe c zurück<br>Parameter<br>? int $a - addend<br>? int $b - summand<br>5. Dokument-Tag: Der Verwendungsbereich des <br> Dokument-Tags bezieht sich auf die Schlüsselwörter oder andere Dokument-Tags, die mit dem Tag geändert werden können. <br>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. <br>@access<br>Verwendungsbereich: Klasse, Funktion, Variable, Definition, Modul<br>Dieses Tag wird verwendet, um die Zugriffsberechtigung von Schlüsselwörtern anzugeben: privat, öffentlich oder geschützt<br>@author<br>Geben Sie an Autor <br>@copyright<br>Verwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, Verwendung<br>Geben Sie Copyright-Informationen an<br>@deprecated<br>Verwendungsbereich: Klasse, Funktion, Variable, Definition, Modul, constent , global, include<br>Zeigt unbenutzte oder veraltete Schlüsselwörter an <br>@example<br>Dieses Tag wird verwendet, um einen Teil des Dateiinhalts zu analysieren und hervorzuheben. PHPdoc versucht, den Inhalt der Datei aus dem durch dieses Tag angegebenen Dateipfad zu lesen <br> @const <br> Verwendungsbereich: define <br> wird verwendet, um die in PHP definierte Konstante anzugeben <br> @ final<br>Verwendungsbereich: Klasse, Funktion, var<br>Gibt an, dass das Schlüsselwort eine endgültige Klasse, Methode, ein Attribut ist und die Ableitung und Änderung verbietet. <br>@filesource<br> ähnelt Beispiel, außer dass dieses Tag den Inhalt der aktuell analysierten PHP-Datei direkt liest und anzeigt. <br>@global<br>Gibt die globale Variable an, auf die in dieser Funktion verwiesen wird.<br>@ingore<br> wird verwendet, um das angegebene Schlüsselwort im Dokument zu ignorieren.<br>@license<br> Äquivalent für im HTML-Tag ist zuerst die URL, dann der anzuzeigende Inhalt <br> Zum Beispiel Baidu< ;/a><br> kann als @license http://www.baidu.com geschrieben werden. Baidu<br>@link<br> ähnelt der Lizenz<br>, kann es aber auch sein verwies auf das Dokument über einen Link. Jedes Schlüsselwort <br>@name<br> gibt einen Alias ​​für das Schlüsselwort an. <br>@package<br>Verwendungsbereich: Seitenebene -> definieren, Funktion, include<br> Klassenebene ->Klasse, Var, Methoden<br> wird verwendet, um eine oder eine logische Anwendung vorzunehmen Mehrere Schlüsselwörter werden zusammengefasst. <br>@abstrcut<br>Gibt an, dass die aktuelle Klasse eine abstrakte Klasse ist<br>@param<br>Gibt die Parameter einer Funktion an<br>@return<br>Gibt den Rückgabezeiger einer Methode oder Funktion an<br>@static<br>Zeigt an, dass der Guan Jianzi statisch ist. <br>@var<br>Geben Sie den Variablentyp an<br>@version<br>Geben Sie die Versionsinformationen an<br>@todo<br>Geben Sie die Bereiche an, die verbessert oder nicht implementiert werden sollten <br>@throws<br> Geben Sie an, dass diese Funktion möglicherweise eine Fehlerausnahme auslöst, die äußerst selten ist. <br>Wie oben erwähnt, müssen normale Dokument-Tags am Anfang jeder Zeile mit @ gekennzeichnet werden. Darüber hinaus gibt es auch ein Tag namens Inline-Tag, das {@} Ausdrücke verwendet umfassen die folgenden Typen: <br>{@link}<br>Verwendung ist die gleiche wie bei @link<br>{@source}<br>Zeigt den Inhalt einer Funktion oder Methode an<br>6. Einige Kommentarspezifikationen <br>a. Kommentare müssen in der Form <br>/**<br>* XXXXXXX<br>*/<br><br>b vorliegen. Für Funktionen, die auf globale Variablen verweisen, müssen GLBOAL-Tags vorliegen verwendet werden. <br>c. Für Variablen müssen ihre Typen (int, string, bool...) mit var markiert sein <br>d Funktionen müssen ihre Parameter und Rückgabewerte durch Parameter- und Rückgabemarker angeben <br>e. Bei zwei Vorkommen Bei Schlüsselwörtern, die zweimal oder häufiger verwendet werden, sollten die redundanten Schlüsselwörter durch Ingore ignoriert und nur eines beibehalten werden <br>f. Wenn andere Funktionen oder Klassen aufgerufen werden, sollten Link- oder andere Tags verwendet werden, um auf die entsprechende Verknüpfung zu verweisen Teil, um die Dokumentation des Lesens zu erleichtern. <br>g. Verwenden Sie bei Bedarf nicht dokumentarische Kommentare, um die Lesbarkeit des Codes zu verbessern. <br>h. Halten Sie den beschreibenden Inhalt prägnant und auf den Punkt und verwenden Sie nach Möglichkeit Phrasen statt Sätze. <br>i.Globale Variablen, Statische Variablen und Konstanten müssen mit entsprechenden Tags beschrieben werden<br>7. Zusammenfassung<br>phpDocumentor ist ein sehr leistungsfähiges Tool zur automatischen Generierung von Dokumenten Es kann uns helfen, standardisierte Kommentare zu schreiben und leicht verständliche, klar strukturierte Dokumente zu erstellen, was für unsere Code-Upgrades, Wartung, Übergabe usw. sehr hilfreich ist.<br>phpDocumentor에 대한 자세한 설명은 공식 홈페이지 <br>http://manual.phpdoc.org/<br>에서 확인하실 수 있습니다.8. 부록<br>부록 1:<br>phpdoc에서 인식할 수 있는 키워드: <br>include<br>require<br>include_once<br>require_once<br>define<br>function<br>global<br>class<br>부록 2<br>문서에서 사용할 수 있는 태그<br> 🎜> &lt;br&gt;&lt;br&gt; &lt;br&gt;<kdb>&lt;br&gt;<li> &lt;br&gt;<div class="code" style="position:relative; padding:0px; margin:0px;"><pre class="brush:php;toolbar:false">&lt;br&gt;</pre><div class="contentsignin">Nach dem Login kopieren</div></div> <ul> &lt;br&gt;<samp>&lt;br&gt;&lt ;var>&lt;br&gt;부록 3: &lt;br&gt;사양 주석이 포함된 PHP 코드&lt;br&gt;<?php&lt;br&gt;/**&lt;br&gt;* 샘플 파일 2, phpDocumentor Quickstart&lt;br&gt;* &lt;br&gt;* 이 파일은 DocBlocks 및 태그를 통해 코드 내 문서에 &lt;br&gt;포함<strong>*할 수 있는</strong>* 풍부한 정보를 보여줍니다.&lt;br&gt;* @author Greg Beaver <celllog@php.net>&lt;br&gt;* @version 1.0&lt;br&gt;* @package 샘플&lt;br&gt;*/&lt;br&gt;// 샘플 파일 #1&lt;br&gt;/ **&lt;br&gt;* phpDocumentor의 구문 분석 능력을 보여주기 위한 더미 &lt;br&gt;include<strong> 값</strong>*/&lt;br&gt;&lt;br&gt;포함<strong>_once 'sample3.php';</strong>/**&lt;br&gt;* 특수 전역 변수 선언 DocBlock&lt;br&gt;* @global 정수 $GLOBALS['_myvar'] &lt;br&gt;* @name $_myvar&lt;br&gt;*/ &lt;br&gt;$GLOBALS['_myvar'] = 6 ;&lt;br&gt;/**&lt;br&gt;* 상수&lt;br&gt;*/&lt;br&gt;/**&lt;br&gt;* 첫 번째 상수&lt;br&gt;*/&lt;br&gt;정의('테스트', 6);&lt;br&gt;/**&lt;br&gt;* 두 번째 상수&lt;br&gt;*/&lt;br&gt;정의 ('anotherconstant', strlen('hello'));&lt;br&gt;/**&lt;br&gt;* 샘플 함수 docblock&lt;br&gt;* @global string 이 함수가 $_myvar을 사용한다는 사실을 문서화합니다.&lt;br&gt;* @staticvar 정수 $staticvar 이것이 실제로 반환되는 내용입니다.&lt;br&gt;* @param string $param1 이름 선언&lt;br&gt;* @param string $param2 이름 값&lt;br&gt;* @return 정수 &lt;br&gt;*/&lt;br&gt;function firstFunc($param1, $param2 = '선택적')&lt;br&gt;{&lt;br&gt; static $staticvar = 7; &lt;br&gt; 전역 $_myvar;&lt;br&gt; return $staticvar;&lt;br&gt;}&lt;br&gt;/**&lt;br&gt;* 첫 번째 예제 클래스는 파일 시작 부분에 있는&lt;br&gt;* 절차 항목과 동일한 패키지에 있습니다.&lt;br&gt;* @package 샘플&lt;br&gt;* @subpackage 클래스&lt;br&gt;*/&lt;br&gt;class myclass {&lt;br&gt; /**&lt;br&gt; * 샘플 개인 변수는 --parseprivate&lt;br&gt; * 옵션&lt;br&gt; * @access private&lt;br&gt; * @var 정수|string&lt;br&gt;으로 숨길 수 있습니다.*/&lt;br&gt; var $firstvar = 6;&lt;br&gt; /**&lt;br&gt; * @link http://www.example.com 예제 링크&lt;br&gt; * @see myclass()&lt;br&gt; * @uses 테스트, anotherconstant&lt;br&gt; * @var 배열 &lt;br&gt;*/&lt;br&gt; var $secondvar =&lt;br&gt; array(&lt;br&gt; 'stuff' =>&lt;br&gt; array(&lt;br&gt; 6, &lt;br&gt; 17,&lt;br&gt; 'armadillo'&lt;br&gt; ),&lt;br&gt; 테스트 => 다른 상수&lt;br&gt; );&lt;br&gt; /**&lt;br&gt; * 생성자는 {@link $firstvar}&lt;br&gt;를 설정합니다.*/&lt;br&gt; 함수 myclass()&lt;br&gt; {&lt;br&gt; $this->firstvar = 7;&lt;br&gt; }&lt;br&gt; /**&lt;br&gt; * $paramie를 기반으로 한 항목 반환&lt;br&gt; * @param boolean $paramie &lt;br&gt; * @return 정수|babyclass&lt;br&gt;*/&lt;br&gt; function parentfunc($paramie)&lt;br&gt; {&lt;br&gt; if ($paramie) { &lt;br&gt; return 6;&lt;br&gt; } else {&lt;br&gt; return new babyclass;&lt;br&gt; }&lt;br&gt; }&lt;br&gt;}&lt;br&gt;/**&lt;br&gt;* @패키지 샘플1&lt;br&gt;*/&lt;br&gt;class babyclass는 myclass를 확장합니다. &lt;br&gt; /**&lt;br&gt; * 인생, 우주, 그리고 모든 것에 대한 답&lt;br&gt; * @var 정수 &lt;br&gt;*/&lt;br&gt; var $secondvar = 42;&lt;br&gt; /**&lt;br&gt; * 구성 값&lt;br&gt; * @var 배열 &lt;br&gt;*/&lt;br&gt; var $thirdvar;&lt;br&gt; /**&lt;br&gt; * 상위 생성자를 호출한 다음 {@link $firstvar}&lt;br&gt;를 증가시킵니다.*/&lt;br&gt; function babyclass()&lt;br&gt; {&lt;br&gt; parent::myclass();&lt;br&gt; $this->firstvar ;&lt;br&gt; }&lt;br&gt; /**&lt;br&gt; * 항상 myclass를 반환합니다&lt;br&gt; * @param은 $paramie를 무시합니다 &lt;br&gt; * @return myclass &lt;br&gt;*/&lt;br&gt; function parentfunc ($paramie )&lt;br&gt; {&lt;br&gt; return new myclass;&lt;br&gt; }&lt;br&gt;}&lt;br&gt;?>&lt;br&gt;</samp> </ul> </li></kdb>