探讨:如何使用PhpDocumentor生成文档_PHP教程-php教程-PHP中文網

首頁

後端開發

php教程

探讨:如何使用PhpDocumentor生成文档_PHP教程

WBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWB

Jul 21, 2016 pm 03:03 PM

phpdocumentor使用命令列在如何探討文件方式產生

命令行方式：
　　在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文当中。

如何书写文档性注释:
　　所有的文档性注释都是由/**开始的一个多行注释，在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息，使得其他人能够通过它知道这个关键字的具体用途，如何使用。PhpDocumentor规定一个DocBlock包含如下信息：
1. 功能简述区
2. 详细说明区
3. 标记tag
　　文档性注释的第一行是功能描述区，正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
　　
在功能描述区后是一个空行，接着是详细说明区,. 这部分主要是详细说明你的API的功能，用途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。
　　
之后同样是一个空白行，然后是文档的标记tag，指明一些技术上的信息，主要是最主要的是调用参数类型，返回值极其类型，继承关系，相关方法/函数等等。

文档注释中还可以使用例如这样的标签，详细介绍请参考附录二。 一个文档注释的例子 /** * 函数add,实现两个数的加法 * * 一个简单的加法计算，函数接受两个数a、b，返回他们的和c * * @param int 加数 * @param int 被加数 * @return integer */ function Add($a, $b) { return $a+$b; } 　　生成文档如下： Add integer Add( int $a, int $b) [line 45] 　　函数add,实现两个数的加法 Constants 一个简单的加法计算，函数接受两个数a、b，返回他们的和c Parameters • int $a - 加数 • int $b - 被加数 文档标记： 　　文档标记的使用范围是指该标记可以用来修饰的关键字，或其他文档标记。 　　所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。 @access 　　使用范围：class,function,var,define,module 　　该标记用于指明关键字的存取权限：private、public或proteced @author 　　指明作者 @copyright 　　使用范围：class，function，var，define，module，use 　　指明版权信息 @deprecated 　　使用范围：class，function，var，define，module，constent，global，include 　　指明不用或者废弃的关键字 @example 　　该标记用于解析一段文件内容，并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容 @const 　　使用范围：define 　　用来指明php中define的常量 @final 　　使用范围：class,function,var 　　指明关键字是一个最终的类、方法、属性，禁止派生、修改。 @filesource 　　和example类似，只不过该标记将直接读取当前解析的php文件的内容并显示。 @global 　　指明在此函数中引用的全局变量 @ingore 　　用于在文档中忽略指定的关键字 @license 　　相当于html标签中的<a>,首先是URL，接着是要显示的内容 　　例如</a><a href="%E2%80%9Dhttp://www.baidu.com%E2%80%9D">百度</a> 　　可以写作 @license http://www.baidu.com 百度 @link 　　类似于license 　　但还可以通过link指到文档中的任何一个关键字 @name 　　为关键字指定一个别名。 @package 　　使用范围：页面级别的-> define，function，include 　　类级别的->class，var，methods 　　用于逻辑上将一个或几个关键字分到一组。 @abstrcut 　　说明当前类是一个抽象类 @param 　　指明一个函数的参数 @return 　　指明一个方法或函数的返回指 @static 　　指明关建字是静态的。 @var 　　指明变量类型 @version 　　指明版本信息 @todo 　　指明应该改进或没有实现的地方 @throws 　　指明此函数可能抛出的错误异常,极其发生的情况 　　上面提到过，普通的文档标记标记必须在每行的开头以@标记，除此之外，还有一种标记叫做inline tag,用{@}表示，具体包括以下几种： {@link} 　　用法同@link {@source} 显示一段函数或方法的内容

一些注释规范
a.注释必须是
/**
* XXXXXXX
*/
　　的形式
b.对于引用了全局变量的函数，必须使用glboal标记。
c.对于变量，必须用var标记其类型（int,string,bool...）
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字，要通过ingore忽略掉多余的，只保留一个即可
f.调用了其他函数或类的地方，要使用link或其他标记链接到相应的部分，便于文档的阅读。
g.必要的地方使用非文档性注释，提高代码易读性。
h.描述性内容尽量简明扼要，尽可能使用短语而非句子。
i.全局变量，静态变量和常量必须用相应标记说明

总结
phpDocumentor是一个非常强大的文档自动生成工具，利用它可以帮助我们编写规范的注释，生成易于理解，结构清晰的文档，对我们的代码升级，维护,移交等都有非常大的帮助。
关于phpDocumentor更为详细的说明，可以到它的官方网站

两个例子：
实例一
实例二

陳述

本文內容由網友自願投稿，版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容，請聯絡admin@php.cn

深入探讨：Django框架是什么？Jan 19, 2024 am 09:23 AM

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

See all articles