Home Backend Development PHP Tutorial How to document your PHP classes (1)_PHP Tutorial

How to document your PHP classes (1)_PHP Tutorial

Jul 21, 2016 pm 02:56 PM
l php one author how document kind translate

How to document your PHP classes (1)


Author: stefano Locati Translation: limodou


You have read about: Object-oriented programming can help you Manage your large web projects and have you started using PHP for object-oriented programming? If you've written several classes to use on your website and you're an organized person, you should have written some documentation about them. But if you are a casual person like me, you will just add some comments in the source code of the class without any other documentation. Without documentation it is difficult to remember the names of methods and how to use them (parameters and meanings). The most typical solution to this situation is to open the source code file and search through hundreds or thousands of statements.


Javadoc-like documentation

There should be a good way - if you have ever used the Java language, you will know the Javadoc documentation system. This tool allows you to insert tags in source code file comments, which can be analyzed by the Javadoc tool to generate a series of HTML pages to document your classes. That way you can have your browser open while you're programming and get a list of classes and a list of class methods with descriptions. When you develop web applications, this can become your reference, improve work efficiency and speed up development.


My opinion is that it is easier and more practical to maintain a reference document within the source code than to maintain a separate document, because this method is easier to keep updated. Otherwise it's very easy to get lazy and postpone updates to the document indefinitely (if I had to put a time limit on it, I'd say 10,000 years). Instead using a tool like this, the only effort is to update a tag near the source code you are modifying, and then run the tool again to generate the updated HTML page.


A preview of some PHP documentation tools

After understanding the above, I searched for what was available, and I found some interesting tools as follows:


phpSearchdoc is part of the enzyme project. Because enzyme is a huge project, it needs to be documented. The developers there have written their own documentation system and they've been generous enough to release it as a standalone package. The resulting document is first written to the database and can then be viewed by some PHP script, like a dynamic web site.


The idea of ​​separating the logic used for analysis from the existing information is quite good, however phpSearchdoc (version 1.01) does not have a real analyzer, but from the source file, even including comments Search for keywords. In fact, it happened to me that the word 'function' was present in one of my comments, and the parser foolishly thought that the word following this word was the name of the function. Even more unfortunately, I happened to put a single quote (') on the same line, and then I tried to write the data to the database, and mysql complained (an error occurred because single quotes are used to separate strings in mysql ).


And it is quite difficult to install and run because it is still an alpha test version. After all it's more of a cross-reference generator than a documentation system, and as I know, you can't add your own comments to functions and methods.


phpxref, as the name suggests, seems more like a cross-reference generation process than a real documentation system. Furthermore, it is more suitable for normal procedural programming rather than object-oriented programming.


The goal of phpautodoc is to be used for PHP like Javadoc is for Java. It looked like the perfect solution for my documentation needs. To test it I had to compile the CGI version of PHP (I usually use the module version), since the generator is written in PHP. I can easily compile and install static executables on a Linux system using these commands:


rm config.chche

make clean

. /configure

make

cp php /usr/local/bin


I decided to test it with its own PHP source code, and I found that it only partially worked Working: It can only generate documentation for classes (generating neat formatting), but not summaries. I don't know if this just happened to happen on my machine, but it stopped with a core dump when trying to generate the summary (PHP 4.0 pl2, RedHat 6.2 environment). If the PHP executable version is installed on your machine/usr/local/bin, the syntax to call it is (in order to get the result I have to give the full path of the php file and output directory)


./phpautodoc -o


phpdoc is a php file used to maintain on a Web site, and it is very suitable for distributed development. Documentation is generated from the database; after installation, you can use the web interface to add your classes to document them. This is indeed interesting, but it is a low-level maintenance method that separates documentation from source code, which is not very convenient for me.


Universal Tools

After the frustration of trying all these tools without much success until the Pear Project came up with a standard solution, I found a working tool that had absolutely nothing to do with PHP at the Open Source Projects at Apple site . The name of the project is HeaderDoc. As the site says "HeaderDoc is a tool that generates HTML reference documentation from comments in C or C++ header files. It is written in Perl for portability. Similar to JavaDoc, it allows developers to easily document Their interface, and output the interface information to HTML "


Yes, you read it right, HeaderDoc only supports C and C++. No other language, but unlike JavaDoc, it relies mostly on markup written in comments, so it can work well with PHP with just a few minor changes (which I'll explain later). These tags are very similar to JavaDoc. Some examples of HeaderDoc tags are @class, @function and @var.


Documenting a class

OK, let’s get into the details now. First let's look at how a class is documented.


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

/*! @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

*/

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


Document a class. You can select the class method in the left frame.


The first thing to note is that the style used to open comments is not exactly like the JavaDoc comment /** (one slash and two asterisks), but replaced by /*! (a slash, an asterisk and an exclamation mark). The tag usage is also different, but they work in a similar way. For example, the first tag is the @class tag, which is used to document a class. This tag is followed by the name of the class. The next tag is the @abstract tag, which

is an optional tag that describes the meaning of a class in a few words, while the @discussion tag is another optional tag used for further discussion. It's of course up to you to decide whether to describe everything in @discussion tags or use @abstract to handle it, but keep in mind that, in general, the more precise the tags you use, the better the results.


Original author: limodou

Source: PHPX

www.bkjia.comtruehttp: //www.bkjia.com/PHPjc/364121.htmlTechArticleHow to document your PHP classes (1) Author: stefano Locati Translation: limodou You have read about: Oriented Object programming can help you manage your large web projects and you're already starting...
Statement of this Website
The content of this article is voluntarily contributed by netizens, and the copyright belongs to the original author. This site does not assume corresponding legal responsibility. If you find any content suspected of plagiarism or infringement, please contact admin@php.cn

Hot AI Tools

Undresser.AI Undress

Undresser.AI Undress

AI-powered app for creating realistic nude photos

AI Clothes Remover

AI Clothes Remover

Online AI tool for removing clothes from photos.

Undress AI Tool

Undress AI Tool

Undress images for free

Clothoff.io

Clothoff.io

AI clothes remover

Video Face Swap

Video Face Swap

Swap faces in any video effortlessly with our completely free AI face swap tool!

Hot Tools

Notepad++7.3.1

Notepad++7.3.1

Easy-to-use and free code editor

SublimeText3 Chinese version

SublimeText3 Chinese version

Chinese version, very easy to use

Zend Studio 13.0.1

Zend Studio 13.0.1

Powerful PHP integrated development environment

Dreamweaver CS6

Dreamweaver CS6

Visual web development tools

SublimeText3 Mac version

SublimeText3 Mac version

God-level code editing software (SublimeText3)

PHP 8.4 Installation and Upgrade guide for Ubuntu and Debian PHP 8.4 Installation and Upgrade guide for Ubuntu and Debian Dec 24, 2024 pm 04:42 PM

PHP 8.4 brings several new features, security improvements, and performance improvements with healthy amounts of feature deprecations and removals. This guide explains how to install PHP 8.4 or upgrade to PHP 8.4 on Ubuntu, Debian, or their derivati

7 PHP Functions I Regret I Didn't Know Before 7 PHP Functions I Regret I Didn't Know Before Nov 13, 2024 am 09:42 AM

If you are an experienced PHP developer, you might have the feeling that you’ve been there and done that already.You have developed a significant number of applications, debugged millions of lines of code, and tweaked a bunch of scripts to achieve op

How To Set Up Visual Studio Code (VS Code) for PHP Development How To Set Up Visual Studio Code (VS Code) for PHP Development Dec 20, 2024 am 11:31 AM

Visual Studio Code, also known as VS Code, is a free source code editor — or integrated development environment (IDE) — available for all major operating systems. With a large collection of extensions for many programming languages, VS Code can be c

Explain JSON Web Tokens (JWT) and their use case in PHP APIs. Explain JSON Web Tokens (JWT) and their use case in PHP APIs. Apr 05, 2025 am 12:04 AM

JWT is an open standard based on JSON, used to securely transmit information between parties, mainly for identity authentication and information exchange. 1. JWT consists of three parts: Header, Payload and Signature. 2. The working principle of JWT includes three steps: generating JWT, verifying JWT and parsing Payload. 3. When using JWT for authentication in PHP, JWT can be generated and verified, and user role and permission information can be included in advanced usage. 4. Common errors include signature verification failure, token expiration, and payload oversized. Debugging skills include using debugging tools and logging. 5. Performance optimization and best practices include using appropriate signature algorithms, setting validity periods reasonably,

How do you parse and process HTML/XML in PHP? How do you parse and process HTML/XML in PHP? Feb 07, 2025 am 11:57 AM

This tutorial demonstrates how to efficiently process XML documents using PHP. XML (eXtensible Markup Language) is a versatile text-based markup language designed for both human readability and machine parsing. It's commonly used for data storage an

PHP Program to Count Vowels in a String PHP Program to Count Vowels in a String Feb 07, 2025 pm 12:12 PM

A string is a sequence of characters, including letters, numbers, and symbols. This tutorial will learn how to calculate the number of vowels in a given string in PHP using different methods. The vowels in English are a, e, i, o, u, and they can be uppercase or lowercase. What is a vowel? Vowels are alphabetic characters that represent a specific pronunciation. There are five vowels in English, including uppercase and lowercase: a, e, i, o, u Example 1 Input: String = "Tutorialspoint" Output: 6 explain The vowels in the string "Tutorialspoint" are u, o, i, a, o, i. There are 6 yuan in total

Explain late static binding in PHP (static::). Explain late static binding in PHP (static::). Apr 03, 2025 am 12:04 AM

Static binding (static::) implements late static binding (LSB) in PHP, allowing calling classes to be referenced in static contexts rather than defining classes. 1) The parsing process is performed at runtime, 2) Look up the call class in the inheritance relationship, 3) It may bring performance overhead.

What are PHP magic methods (__construct, __destruct, __call, __get, __set, etc.) and provide use cases? What are PHP magic methods (__construct, __destruct, __call, __get, __set, etc.) and provide use cases? Apr 03, 2025 am 12:03 AM

What are the magic methods of PHP? PHP's magic methods include: 1.\_\_construct, used to initialize objects; 2.\_\_destruct, used to clean up resources; 3.\_\_call, handle non-existent method calls; 4.\_\_get, implement dynamic attribute access; 5.\_\_set, implement dynamic attribute settings. These methods are automatically called in certain situations, improving code flexibility and efficiency.

See all articles