search
HomeBackend DevelopmentPHP TutorialDiscussion: How to use PhpDocumentor to generate documents_PHP Tutorial
Discussion: How to use PhpDocumentor to generate documents_PHP TutorialJul 21, 2016 pm 03:03 PM
phpdocumentoruseCommand LineexisthowDiscussdocumentWaygenerate

命令行方式:
  在phpDocumentor所在目录下,输入phpdoc –h会得到一个详细的参数表,其中几个重要的参数如下:
-f 要进行分析的文件名,多个文件用逗号隔开
-d 要分析的目录,多个目录用逗号分割
-t 生成的文档的存放路径
-o 输出的文档格式,结构为输出格式:转换器名:模板目录。
  例如:phpdoc -o HTML:frames:earthli -f test.php -t docs

Web界面生成
  在新的phpdoc中,除了在命令行下生成文档外,还可以在客户端浏览器上操作生成文档,具体方法是先把PhpDocumentor的内容放在apache目录下使得通过浏览器可以访问到,访问后显示如下的界面:
  点击files按钮,选择要处理的php文件或文件夹,还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
  然后点击output按钮来选择生成文档的存放路径和格式.
  最后点击create,phpdocumentor就会自动开始生成文档了,最下方会显示生成的进度及状态,如果成功,会显示
Total Documentation Time: 1 seconds
done
Operation Completed!!
然后,我们就可以通过查看生成的文档了,如果是pdf格式的,名字默认为documentation.pdf。
给php代码添加规范的注释

PHPDocument是从你的源代码的注释中生成文档,因此在给你的程序做注释的过程,也就是你编制文档的过程。
  从这一点上讲,PHPdoc促使你要养成良好的编程习惯,尽量使用规范,清晰文字为你的程序做注释,同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
  在phpdocumentor中,注释分为文档性注释和非文档性注释。
  所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等,具体的可参加附录1.
  那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。

How to write documentation comments:
All documentation comments are composed of /**The first multi-line comment is called DocBlock in phpDocumentor. DocBlock refers to the help information about a certain keyword written by software developers, so that others can know the specific purpose of this keyword and how to use it. PhpDocumentor stipulates that a DocBlock contains the following information:
1. Function brief description area
2. Detailed description area
3. Tag tag
The first line of documentation comments is the function In the description area, the text generally briefly describes the function of this class, method or function. The text of the brief function description will be displayed in the index area in the generated document. The content of the function description area can be ended by a blank line or.
 
After the function description area is a blank line, followed by a detailed description area. This part mainly describes the functions and uses of your API in detail , if possible, you can also provide examples of usage, etc. In this section, you should focus on clarifying the general purpose and usage of your API functions or methods, and indicate whether it is cross-platform (if involved). For platform-related information, you should treat it differently from general information. , the usual approach is to start a new line, and then write the precautions or special information on a specific platform. This information should be enough so that your readers can write corresponding test information, such as boundary conditions, parameter ranges, Breakpoints, etc.
There is also a blank line after
, and then the document tag, indicating some technical information, mainly the call parameter type, return value and type, inheritance relationship, related methods/functions, etc. wait.

You can also use tags such as in document comments. Please refer to Appendix 2 for details. <br><strong>An example of a documentation comment<br></strong>/**<br>* The function add implements the addition of two numbers <br>*<br>* A simple addition calculation, the function accepts two Numbers a and b, return their sum c<br>*<br>* @param int addend<br>* @param int summand<br>* @return integer<br>*/<br>function Add($a, $b)<br>{ <br>return $a+$b;<br>}<br> The generated document is as follows: <br>Add<br>integer Add(int $a, int $b)<br>[line 45]<br> Function add , implement the addition of two numbers<br>Constants A simple addition calculation, the function accepts two numbers a, b, and returns their sum c<br>Parameters<br>• int $a - addend<br>• int $b - summand <br><strong>Document tag: <br></strong> The scope of use of document tags refers to the keywords or other document tags that the tag can be used to modify. <br> All documentation tags begin with @ after * on each line. If the @ mark appears in the middle of a paragraph, the mark will be treated as normal content and ignored. <br><strong>@access<br></strong> Scope of use: class, function, var, define, module<br> This tag is used to indicate the access permission of keywords: private, public or protected<br><strong>@author<br></strong> Specify the author <br><strong>@copyright<br></strong> Scope of use: class, function, var, define, module, use<br> Specify the copyright information <br><strong>@deprecated<br></strong>Usage scope: class, function, var, define, module, constent, global, include<br>Specify unused or obsolete keywords<br><strong>@example<br></strong> This tag is used to parse a piece of file content and highlight them. Phpdoc will try to read the file content from the file path given by this tag <br><strong>@const<br></strong> Usage scope: define<br> Used to specify the constant of define in php <br><strong> @final<br></strong> Usage scope: class, function, var<br> Indicates that the keyword is a final class, method, attribute, and derivation and modification are prohibited. <br><strong>@filesource<br></strong> Similar to example, except that this tag will directly read the content of the currently parsed php file and display it. <br><strong>@global<br></strong>Specifies the global variable referenced in this function<br><strong>@ingore<br></strong> Used to ignore the specified keyword in the document<br> <strong>@license<br></strong> Equivalent to <a> in the html tag, first the URL, then the content to be displayed <br> For example </a><a href="http://www.baidu.%20com%E2%80%9D>Baidu</a><BR>Can%20be%20written%20as%20@license%20http://www.baidu.com%20Baidu<BR><STRONG>@link<BR></STRONG>%20Similar%20to%20license<BR>%20but%20still%20okay%20Point%20to%20any%20keyword%20in%20the%20document%20through%20link%20<BR><STRONG>@name<BR></STRONG>%20Specify%20an%20alias%20for%20the%20keyword.%20<BR><STRONG>@package<BR></STRONG>%20Scope%20of%20use:%20page%20level%20->%20define,%20function,%20include<BR>%20Class%20level%20->class,%20var,%20methods<BR>%20Used%20to%20logically%20apply%20One%20or%20several%20keywords%20are%20grouped%20together.%20<BR><STRONG>@abstrcut<BR></STRONG>%E3%80%80Indicates%20that%20the%20current%20class%20is%20an%20abstract%20class<BR><STRONG>@param<BR></STRONG>Specifies%20the%20parameters%20of%20a%20function%20<BR><STRONG>@return<BR></STRONG>Specifies%20the%20return%20pointer%20of%20a%20method%20or%20function<BR><STRONG>@static<BR></STRONG>Specifies%20that%20the%20keyword%20is%20static.<BR><STRONG>@var<BR></STRONG>%20Specify%20the%20variable%20type%20<BR><STRONG>@version<BR></STRONG>%20Specify%20the%20version%20information%20<BR><STRONG>@todo<BR></STRONG>%20Specify%20what%20should%20be%20Improvements%20or%20areas%20that%20are%20not%20implemented%20<BR><STRONG>@throws<BR></STRONG>%20Indicate%20the%20error%20exceptions%20that%20this%20function%20may%20throw,%20and%20the%20extreme%20situations%20<BR>%20As%20mentioned%20above,%20ordinary%20document%20markup%20tags%20must%20be%20included%20in%20each%20The%20beginning%20of%20the%20line%20is%20marked%20with%20@.%20In%20addition,%20there%20is%20also%20a%20tag%20called%20inline%20tag,%20which%20is%20represented%20by%20%7B@%7D,%20including%20the%20following%20types:%20<BR>%7B@link%7D<BR>%20The%20usage%20is%20the%20same%20as%20@link<BR>%7B%20@source%7D<BR>Display%20the%20content%20of%20a%20function%20or%20method</P>%0A<P><STRONG>Some%20comment%20specifications<BR></STRONG>a.%20Comments%20must%20be%20in%20the%20form%20of%20<BR>/**<BR>*%20XXXXXXX<BR>*/<BR>%E3%80%80<BR>b.%20For%20functions%20that%20reference%20global%20variables,%20they%20must%20Use%20glboal%20tag.%20<BR>c.%20For%20variables,%20their%20types%20(int,%20string,%20bool...)%20must%20be%20marked%20with%20var%20<BR>d.%20Functions%20must%20indicate%20their%20parameters%20and%20return%20values%20%E2%80%8B%E2%80%8Bthrough%20param%20and%20return%20markers%20<BR>e.%20For%20two%20occurrences%20For%20keywords%20used%20twice%20or%20more,%20the%20redundant%20ones%20should%20be%20ignored%20through%20ingore,%20and%20only%20one%20should%20be%20kept%20<BR>f.%20Where%20other%20functions%20or%20classes%20are%20called,%20link%20or%20other%20tags%20should%20be%20used%20to%20link%20to%20the%20corresponding%20part%20to%20facilitate%20documentation.%20of%20reading.%20<BR>g.%20Use%20non-documentation%20comments%20where%20necessary%20to%20improve%20code%20readability.%20<BR>h.%20Keep%20descriptive%20content%20concise%20and%20to%20the%20point,%20using%20phrases%20rather%20than%20sentences%20whenever%20possible.%20<BR>i.%20Global%20variables,%20static%20variables%20and%20constants%20must%20be%20declared%20with%20corresponding%20tags</P>%0A<P><STRONG><FONT%20style=" color:>Summary<br>phpDocumentor is a very powerful document automatic generation tool. It can help us write standardized comments and generate easy-to-understand, clear-structured documents. Our code upgrades, maintenance, handovers, etc. are all very helpful. <br>For more detailed instructions about phpDocumentor, you can go to its official website </a>

Two examples:
Example 1
Example 2

www.bkjia.comtruehttp: //www.bkjia.com/PHPjc/327852.htmlTechArticleCommand line method: In the directory where phpDocumentor is located, enter phpdoc –h and you will get a detailed parameter list, including several The important parameters are as follows: -f The file name to be analyzed, multiple...
Statement
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
深入探讨:Django框架是什么?深入探讨:Django框架是什么?Jan 19, 2024 am 09:23 AM

Django框架是一种用于Web应用程序的Python框架,它提供了一个简单而强大的方式来创建Web应用程序。事实上,Django已经成为当前最受欢迎的PythonWeb开发框架之一,也成为很多公司的首选,包括Instagram和Pinterest。本文将深入探讨Django框架是什么,包括基础概念和重要组件,以及具体代码示例。Django基础概念Djan

深入探讨Laravel中的Head请求方法深入探讨Laravel中的Head请求方法Mar 06, 2024 pm 03:36 PM

作为一个流行的PHP框架,Laravel提供了许多便捷的请求方法来处理不同类型的HTTP请求。其中,Head请求方法是一个比较特殊且常被忽视的方法。在本文中,我们将深入探讨Laravel中Head请求方法的作用、用法和示例代码。什么是Head请求方法?Head请求方法是HTTP协议中定义的一种请求方法,在发送Head请求时,服务器将仅返回请求头信息,而不会返

深入探讨Go语言对C语言的兼容程度深入探讨Go语言对C语言的兼容程度Mar 07, 2024 pm 02:45 PM

Go语言是一门由Google开发的编程语言,具有高效、简洁、并发性强等特点。它在语法结构、包管理、高级特性等方面都有很大的优势,因此备受程序员青睐。然而,在实际开发中,很多项目会涉及到与传统的编程语言C进行交互,因此Go语言与C语言的兼容性就显得尤为重要。首先,我们来谈谈Go语言与C语言的兼容性。在Go语言中,可以通过CGo将Go语言与C语言进行交互。CGo

深入探讨:Go语言中的单线程特性深入探讨:Go语言中的单线程特性Mar 15, 2024 pm 02:09 PM

Go语言作为一种现代化的编程语言,以其简洁高效的特性在近年来受到越来越多开发者的喜爱和青睐。其中一个让人独特的地方就是其单线程特性。在传统的多线程编程语言中,开发者通常需要手动管理线程之间的同步和互斥,而在Go语言中,借助其独特的协程(Goroutine)和通信机制(channel),可以方便且高效地实现并发编程。一、Goroutine与单线程:Go语言中的

深入探讨:Golang是否适合编写驱动程序?深入探讨:Golang是否适合编写驱动程序?Mar 20, 2024 am 10:09 AM

Golang是一种由谷歌开发的编程语言,其出色的性能和并发特性使其在各种领域中得到了广泛的应用,包括网络编程、大数据处理等。然而,对于一些需要直接操作硬件的领域,比如驱动程序开发,人们可能会开始思考:Golang是否适合用于编写驱动程序呢?本文将深入探讨这个问题,并通过具体的代码示例来展示Golang在驱动程序开发中的应用。首先,让我们来了解一下什么是驱动程

理解MyBatis:深入探讨其作用和特点理解MyBatis:深入探讨其作用和特点Feb 22, 2024 pm 03:48 PM

MyBatis(又称为iBatis)是一个流行的Java持久层框架,其设计理念是以SQL为核心,在实现SQL和Java对象的映射过程中提供了方便灵活的操作接口。MyBatis通过XML或注解方式配置SQL语句,并提供了丰富的查询方式,使得开发者可以更加直观地编写数据库操作的代码。本文将深入探讨MyBatis的作用和特点,以及提供具体的代码示例加以说明。作用和

Golang的本质是脚本语言还是编译语言?探讨Golang的本质是脚本语言还是编译语言?探讨Mar 19, 2024 pm 03:12 PM

Golang的本质是脚本语言还是编译语言?探讨Golang,也被称为Go语言,是一种由Google开发的静态类型编程语言。自诞生以来,Golang一直备受开发者关注,其优秀的并发性能、简洁的语法和跨平台特性使其在各个领域得到广泛应用。然而,关于Golang到底是脚本语言还是编译语言,却一直存在着争议。脚本语言和编译语言在运行时的不同方式给人们留下了深刻的印象

深入探讨Linux中常见的特殊字符深入探讨Linux中常见的特殊字符Mar 14, 2024 pm 02:54 PM

Linux操作系统作为一种常用的开源操作系统,具有强大的可定制性和灵活性。在使用Linux系统时,我们经常会遇到各种特殊字符的处理。这些特殊字符在命令行中具有特殊的含义,能够实现很多高级功能。本文将深入探讨Linux中常见的特殊字符,并结合具体的代码示例来详细介绍它们的用法。通配符:通配符是用来匹配文件名的特殊字符,常见的通配符包括*、?、[]等。下面是几种

See all articles

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

AI Hentai Generator

AI Hentai Generator

Generate AI Hentai for free.

Hot Article

R.E.P.O. Energy Crystals Explained and What They Do (Yellow Crystal)
2 weeks agoBy尊渡假赌尊渡假赌尊渡假赌
Repo: How To Revive Teammates
4 weeks agoBy尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island Adventure: How To Get Giant Seeds
4 weeks agoBy尊渡假赌尊渡假赌尊渡假赌

Hot Tools

PhpStorm Mac version

PhpStorm Mac version

The latest (2018.2.1) professional PHP integrated development tool

Safe Exam Browser

Safe Exam Browser

Safe Exam Browser is a secure browser environment for taking online exams securely. This software turns any computer into a secure workstation. It controls access to any utility and prevents students from using unauthorized resources.

SublimeText3 English version

SublimeText3 English version

Recommended: Win version, supports code prompts!

Dreamweaver CS6

Dreamweaver CS6

Visual web development tools

SublimeText3 Mac version

SublimeText3 Mac version

God-level code editing software (SublimeText3)