【php相关知识】如何生成一个库的php文档 ?

最近有在考虑一个问题,就是如何生成一个关于自己写好的PHP文件或者库的完整的文档,这样别人在使用的时候就可以对照文档进行理解.
有句话说的好,优秀的程序看源码,优秀的工具看文档。如果你开发的一个框架或者库没有好的文档支撑。估计也不会有太多人的愿意去使用。当然这句话的原意不太清楚了。
接下来我就来介绍下今天刚刚使用的PHP文档生成工具 phpDoctor
github地址: https://github.com/peej/phpdoctor
官网地址: http://www.peej.co.uk/phpdoctor/

安装方式
使用composer 安装

composer init
# 输入基本的配置后 会生成一个composer.json 的文件
# 添加一个依赖
require :{
     "peej/phpdoctor": "2.0.5"
}
# 然后使用 composer install 或者 composer update 进行安装/更新

此时可以进入vendor/bin 目录下,发现多了两个命令,分别是linux下的命令和windows下的命令.

phpDoctor 配置
在vendor目录下,实际上还有其它的目录生成

cd vendor/peej/phpdoctor

实际上我们运行命令行的本意就是
php phpdoc.php
default.ini 有一些默认的参数配置,里面有些介绍,一般我不会进行修改。

如果想要自定义一个目标库的文档生成,可以在 examples目录下拷贝一个phpdoctor.ini 文件,然后进行修改。

; Configuration file generating docs for PHPDoctor

; Run from within the PHPDoctor directory, for example:
;  ~/phpdoctor$ php phpdoc.php examples/phpdoctor.ini

; This config file will cause PHPDoctor to generate API documentation of
; itself.


; PHPDoctor settings
; -----------------------------------------------------------------------------

; Names of files to parse. This can be a single filename, or a comma separated
; list of filenames. Wildcards are allowed.
; 指定的解析文件后缀类型
files = "*.php"

; Names of files or directories to ignore. This can be a single filename, or a
; comma separated list of filenames. Wildcards are NOT allowed.
; 忽略文件夹和文件后缀
ignore = "CVS, .svn, .git, _compiled"

; The directory to look for files in, if not used the PHPDoctor will look in
; the current directory (the directory it is run from).
; 源文件路径 指的是库文件的地址 
;source_path = "./"

; If you do not want PHPDoctor to look in each sub directory for files
; uncomment this line.

;subdirs = off

; Set how loud PHPDoctor is as it runs. Quiet mode suppresses all output other
; than warnings and errors. Verbose mode outputs additional messages during
; execution.

;quiet = on
;verbose = on

; Select the doclet to use for generating output.

doclet = standard
;doclet = debug

; The directory to find the doclet in. Doclets are expected to be in a
; directory named after themselves at the location given.

;doclet_path = ./doclets

; The directory to find taglets in. Taglets allow you to make PHPDoctor handle
; new tags and to alter the behavour of existing tags and their output.

;taglet_path = ./taglets

; If the code you are parsing does not use package tags or not all elements
; have package tags, use this setting to place unbound elements into a
; particular package.
; 默认文件包名称
default_package = "PHPDoctor"

; Specifies the name of a HTML file containing text for the overview
; documentation to be placed on the overview page. The path is relative to
; "source_path" unless an absolute path is given.

overview = readme.html

; Package comments will be looked for in a file named package.html in the same
; directory as the first source file parsed in that package or in the directory
; given below. If package comments are placed in the directory given below then
; they should be named "<packageName>.html".

package_comment_dir = ./

; Parse out global variables and/or global constants?

;globals = off
;constants = off

; Generate documentation for all class members

;private = on

; Generate documentation for public and protected class members

;protected = on

; Generate documentation for only public class members

;public = on

; Standard doclet settings
; -----------------------------------------------------------------------------

; The directory to place generated documentation in. If the given path is
; relative to it will be relative to "source_path".
; 输出文档目标地址
d = "examples/phpdoctor"

; Specifies the title to be placed in the HTML <title> tag.
; 浏览器窗口的标题
windowtitle = "PHPDoctor"

; Specifies the title to be placed near the top of the overview summary file.
; 文档内容的标题
doctitle = "PHPDoctor: The PHP Documentation Creator"

; Specifies the header text to be placed at the top of each output file. The
; header will be placed to the right of the upper navigation bar. 
; 
header = "PHPDoctor"

; Specifies the footer text to be placed at the bottom of each output file. The
; footer will be placed to the right of the lower navigation bar.

footer = "PHPDoctor"

; Specifies the text to be placed at the bottom of each output file. The text
; will be placed at the bottom of the page, below the lower navigation bar.

;bottom = "This document was generated by <a href="http://peej.github.com/phpdoctor/">PHPDoctor: The PHP Documentation Creator</a>"

; Create a class tree?

;tree = off

; Use GeSHi to include formatted source files in the documentation

;include_source = off

相关的介绍都附加在了上述的注释中,接下来我们来生成一个Yii框架的文档吧.

准备阶段
1. 下载Yii 1.1.*框架源码。官网地址：http://www.yiiframework.com/download/
2. 配置YiiDoc.ini文件

files = "*.php"

ignore = "CVS, .svn, .git, _compiled"

source_path = "C:\Users\liyl\PhpstormProjects\yii-1.1.10.r3566\framework"

doclet = standard

default_package = "Yii-1.1.10"

overview = readme.html

package_comment_dir = ./

d = "C:\Users\liyl\PhpstormProjects\yii-1.1.10.r3566\doc"

windowtitle = "Yii-1.1.10"

doctitle = "Yii: The PHP Documentation Creator"

header = "Yii"

footer = "Yii"

使用命令行

Result: