如何文档化你的PHP类(一)_PHP教程-PHP-Tutorial-php.cn

Heim

Backend-Entwicklung

PHP-Tutorial

如何文档化你的PHP类(一)_PHP教程

WBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWB

Jul 21, 2016 pm 02:56 PM

lphpeinsAutor如何文档类翻译

如何文档化你的PHP类(一)

作者：stefano Locati 翻译：limodou

　　你已经阅读过关于：面向对象编程可以帮助你管理你的大型web项目，并且你已经开始使用PHP来进行面向对象编程了吗？如果你已经编写了几个类应用在网站上并且你是一个有条理的人的话，那么你应该已经编写了关于它们的一些文档。但是如果你是一个象我一样的不拘小节的人，你只是会在类的源代码中加一些注释而没有别的文档。没有文档就很难记住方法的名字和它们的使用方法（参数和含义）。解决这种情况最典型的办法就是打开源代码文件，从成百上千的语句中查找。

类似Javadoc的文档

　　应该有一种好的方法----如果你曾经使用过Java语言，你将知道Javadoc文档系统。这个工具允许你在源代码文件注释中插入一些标记，这些标记可以被Javadoc工具进行分析以便生成一系列的HTML页面把你的类文档化。那样在编程的同时你可以开着浏览器并且可以得到类列表和带有说明的类方法的列表。在你开发web应用时，这个可以成为你的参考，提高工作效率和加快开发速度。

　　我的意见是维护一个作为源代码内的引用文档要比维护一个独立的文档要容易和更实用，因为这个方法更容易保持更新。否则就非常容易变得懒惰从而将对文档的更新推后到无限期（如果一定要给它加个期限，我想是一万年）。相反使用象这样的一个工具，只有一点工作量就是在你正在修改的源代码附近更新一个标记，接着运行工具再一次生成更新过的HTML页面。

一些php文档工具的预览

　　在对上面了解了之后，我搜索了一下哪些是可用的，并且我发现了如下一些有趣的工具：

　　phpSearchdoc是enzyme项目的一部分。因为enzyme 是一个巨大的项目，所以需要将其文档化。那里的开发人员已经编写了他们自已的文档系统并且他们非常慷慨地将其作为一个独立的包进行发布。得到的文档首先被写入数据库，然后可以被一些PHP脚本查看，象一个动态的web站点。

　　从现存的信息中将用于分析的逻辑分离出来的想法相当好，然而phpSearchdoc(版本 1.01)不具有一个真正的分析器，而是从源文件，甚至包括注释中搜索关键字。事实上，对我来说碰巧发生过在我的注释中存在'function'单词，结果分析器愚蠢地认为在这个单词后面的词就是函数的名字。更不幸的是，我不巧在同一行放了一个单引号(')，接着我试图将数据写到数据库中，mysql作出了抱怨（出错了，因为单引号在 mysql中被用于分割字符串）。

　　而且它的安装及运行相当困难，因为它还是一个alpha测试版。毕竟比起文档系统来说它更象是一个交叉引用生成器，正如我知道的，你不能在函数和方法中加入自已的注释。

　　phpxref，就象名字所指的比起一个真正的文档系统来似乎更象是面向交叉引用的生成处理。更进一步说它更适合于正常的过程化编程而不是面向对象编程。

　　phpautodoc的目标是实现象Javadoc 应用于Java那样用于PHP。它看上去是满足我的文档需求的完美解决。为了试验它我不得不编译了PHP的CGI版本（我通常使用模块版本），因为生成器是用PHP编的。我可能容易地在一个Linux系统下编译和安装静态的执行程序，可以使用这些命令：

rm config.chche

make clean

./configure

make

cp php /usr/local/bin

　　我决定对它自已的PHP源码进行测试，并且我发现它只有部分可以工作：它只能够生成类的文档（生成整齐的格式），但是不能生成小结。我不知道是否这个只是碰巧发生在我的机器上，但是在试图生成小结时却因为core dump(内核崩溃)而停止（PHP 4.0 pl2，RedHat 6.2环境）。假如在你的机器/usr/local/bin下安装了PHP执行版本，调用它的语法是（为了得到结果我不得不给出php文件和输出目录的全路径）

./phpautodoc -o

　　phpdoc是一个用来维护在Web站点上的php 文件，并且它非常适合分布式开发方式。文档是从数据库中生成；在安装之后，你可以使用web界面来增加你的类将其文档化。这个的确有意思，但是它是一种低级的从源代码中分离文档的维护方法，这一点就我来说不是非常方便。

通用工具

　　在经受了试验所有这些工具但却得不到怎么成功的挫折之后，直到Pear Project提出了一种标准的解决方法，我发现了一个与PHP完全无关的可工作的工具在Open Source Projects at Apple站点。项目的名字是 HeaderDoc。就象站点所说的" HeaderDoc是一种从C或C++头文件的注释中生成HTML的引用文档的工具。它是用Perl编写的以便于移植。与JavaDoc 相似，它允许开发者容易地文档化他们的接口，并且将接口信息输出到HTML。"

　　是的，你看的没错，HeaderDoc只支持C和C++。没有其它的语言，但是它不象JavaDoc，它大部分依赖写在注释中的标记，所以只要做些小改动（我会在后面解释）就可以很好的用在PHP上。这些标记同JavaDoc很象，HeaderDoc标记的一些例子是@class，@function和@var。

文档化一个类

　　OK，让我们现在进入细节吧。首先让我们看一下一个类如何被文档化。

--------------------------------------------------------------------------------

/*! @class BagItem

@abstract An item in the shopping bag - it is a shopitem with quantity

@discussion A BagItem object may be constructed without previous

instantiation of neither ShopItem nor Product

*/

--------------------------------------------------------------------------------

文档化一个类。可以在左边的帧选择类的方法。

　　第一件需要注意的事情是用在打开注释上的风格不完全象JavaDoc注释/**(一个斜线和两个星号)，而是换成/*!(一个斜线，一个星号和一个感叹号) 。标记使用也不一样，但是它们以相似的方式工作。例如，第一个标记是@class标记，它用于文档化一个类，这个标记跟着类的名字。下一个标记是@abstract 标记，它

是一个可选的标记，用少量词语来描述一个类的含义，同时@discussion 标记是另一个可选的标记，用于进一步的讨论。当然由你来决定是在@discussion标记中描述所有的事情还是使用@abstract来处理，但是要记住，一般来说，你使用的标记越精确，结果就越好。

原作者：limodou

来源：PHPX

Stellungnahme

Der Inhalt dieses Artikels wird freiwillig von Internetnutzern beigesteuert und das Urheberrecht liegt beim ursprünglichen Autor. Diese Website übernimmt keine entsprechende rechtliche Verantwortung. Wenn Sie Inhalte finden, bei denen der Verdacht eines Plagiats oder einer Rechtsverletzung besteht, wenden Sie sich bitte an admin@php.cn

Verwandter Artikel

Wie funktioniert der Php -Typ -Hinweis, einschließlich Skalartypen, Rückgabetypen, Gewerkschaftstypen und nullbaren Typen?Apr 17, 2025 am 12:25 AM

PHP -Typ -Eingabeaufforderungen zur Verbesserung der Codequalität und der Lesbarkeit. 1) Tipps zum Skalartyp: Da Php7.0 in den Funktionsparametern wie int, float usw. angegeben werden dürfen. 3) Eingabeaufforderung für Gewerkschaftstyp: Da Php8.0 in Funktionsparametern oder Rückgabetypen angegeben werden dürfen. 4) Nullierstyp Eingabeaufforderung: Ermöglicht die Einbeziehung von Nullwerten und Handlungsfunktionen, die Nullwerte zurückgeben können.

Wie handelt es sich bei PHP -Objektklonen (Klonschlüsselwort) und der __clone Magic -Methode?Apr 17, 2025 am 12:24 AM

Verwenden Sie in PHP das Klonschlüsselwort, um eine Kopie des Objekts zu erstellen und das Klonierungsverhalten über die \ _ \ _ Clone Magic -Methode anzupassen. 1. Verwenden Sie das Klonschlüsselwort, um eine flache Kopie zu erstellen und die Eigenschaften des Objekts, nicht die Eigenschaften des Objekts zu klonen. 2. Die \ _ \ _ Klonmethode kann verschachtelte Objekte tief kopieren, um flache Kopierprobleme zu vermeiden. 3. achten Sie darauf, dass kreisförmige Referenzen und Leistungsprobleme beim Klonen vermieden werden, und optimieren Sie die Klonierungsvorgänge, um die Effizienz zu verbessern.

PHP vs. Python: Anwendungsfälle und AnwendungenApr 17, 2025 am 12:23 AM

PHP eignet sich für Webentwicklungs- und Content -Management -Systeme, und Python eignet sich für Datenwissenschafts-, maschinelles Lernen- und Automatisierungsskripte. 1.PHP hat eine gute Leistung beim Erstellen von schnellen und skalierbaren Websites und Anwendungen und wird üblicherweise in CMS wie WordPress verwendet. 2. Python hat sich in den Bereichen Datenwissenschaft und maschinelles Lernen mit reichen Bibliotheken wie Numpy und TensorFlow übertrifft.

Beschreiben Sie verschiedene HTTP-Caching-Header (z. B. Cache-Control, ETAG, Last-modifiziert).Apr 17, 2025 am 12:22 AM

Zu den wichtigsten Spielern in HTTP-Cache-Headern gehören Cache-Control, ETAG und Last-modifiziert. 1.Cache-Control wird verwendet, um die Richtlinien zu kontrollieren. Beispiel: Cache-Control: max-ay = 3600, öffentlich. 2. ETAG überprüft Ressourcenänderungen durch eindeutige Identifikatoren, Beispiel: ETAG: "686897696A7C876B7E". 3. Last-modifiziert gibt die letzte Änderungszeit der Ressource an, Beispiel: Last-Modified: Mi, 21okt201507: 28: 00GMT.

Erklären Sie sicheres Kennwort -Hashing in PHP (z. B. password_hash, password_verify). Warum nicht MD5 oder SHA1 verwenden?Apr 17, 2025 am 12:06 AM

In PHP sollten die Funktionen für Passwort_Hash und passwart_verify verwendet werden, um sicheres Passwort -Hashing zu implementieren, und MD5 oder SHA1 sollte nicht verwendet werden. 1) Passwort_hash generiert einen Hash, der Salzwerte enthält, um die Sicherheit zu verbessern. 2) Passwort_Verify prüfen Sie das Passwort und sicherstellen Sie die Sicherheit, indem Sie die Hash -Werte vergleichen. 3) MD5 und SHA1 sind anfällig und fehlen Salzwerte und sind nicht für die Sicherheit der modernen Passwort geeignet.

PHP: Eine Einführung in die serverseitige SkriptspracheApr 16, 2025 am 12:18 AM

PHP ist eine serverseitige Skriptsprache, die für dynamische Webentwicklung und serverseitige Anwendungen verwendet wird. 1.PHP ist eine interpretierte Sprache, die keine Zusammenstellung erfordert und für die schnelle Entwicklung geeignet ist. 2. PHP -Code ist in HTML eingebettet, wodurch es einfach ist, Webseiten zu entwickeln. 3. PHP verarbeitet die serverseitige Logik, generiert die HTML-Ausgabe und unterstützt Benutzerinteraktion und Datenverarbeitung. 4. PHP kann mit der Datenbank interagieren, die Einreichung von Prozessformularen und serverseitige Aufgaben ausführen.

PHP und das Web: Erforschen der langfristigen AuswirkungenApr 16, 2025 am 12:17 AM

PHP hat das Netzwerk in den letzten Jahrzehnten geprägt und wird weiterhin eine wichtige Rolle bei der Webentwicklung spielen. 1) PHP stammt aus dem Jahr 1994 und ist aufgrund seiner Benutzerfreundlichkeit und der nahtlosen Integration in MySQL die erste Wahl für Entwickler. 2) Zu den Kernfunktionen gehört das Generieren dynamischer Inhalte und die Integration in die Datenbank, sodass die Website in Echtzeit aktualisiert und auf personalisierte Weise angezeigt wird. 3) Die breite Anwendung und das Ökosystem von PHP hat seine langfristigen Auswirkungen angetrieben, steht jedoch auch mit Versionsaktualisierungen und Sicherheitsherausforderungen gegenüber. 4) Leistungsverbesserungen in den letzten Jahren, wie die Veröffentlichung von PHP7, ermöglichen es ihm, mit modernen Sprachen zu konkurrieren. 5) In Zukunft muss PHP sich mit neuen Herausforderungen wie Containerisierung und Microservices befassen, aber seine Flexibilität und die aktive Community machen es anpassungsfähig.

Warum PHP verwenden? Vorteile und Vorteile erläutertApr 16, 2025 am 12:16 AM

Zu den Kernvorteilen von PHP gehören einfacher Lernen, starke Unterstützung für Webentwicklung, reiche Bibliotheken und Rahmenbedingungen, hohe Leistung und Skalierbarkeit, plattformübergreifende Kompatibilität und Kosteneffizienz. 1) leicht zu erlernen und zu bedienen, geeignet für Anfänger; 2) gute Integration in Webserver und unterstützt mehrere Datenbanken. 3) leistungsstarke Frameworks wie Laravel; 4) hohe Leistung kann durch Optimierung erzielt werden; 5) mehrere Betriebssysteme unterstützen; 6) Open Source, um die Entwicklungskosten zu senken.

See all articles