第二个灵魂 发表于 2015-2-4 00:27:10

PHP编程:PEAR:利用PHPDoc轻松创立你的PEAR文档...

熟悉了PHP和MYSQL开发的要领之后,再回头看你写的那个留言本,你也许会怀疑那真的是你写的吗?当然,如果屋里还有鬼的话,也许是它写的-_-   关于一个开辟人员,文档老是最感应头疼的工作之一。并且,极可能你看待文档会接纳一模一样的2种立场:

当你利用他人的代码库的时分,最但愿失掉的是它的手艺文档,特别是事先间很紧,而你又不能不硬着头皮去读那些生涩的代码的时分。

当写你本人的法式的时分,最不但愿做的工作倒是给它编写专门的手艺文档,你会以各种来由给本人摆脱:我的代码已足够明晰了,完整不必再为它从头编写文档了……

或许是为了减缓这类抵触,有良多东西可以匡助你,经由过程从源代码中抽取响应的正文,可以主动生成响应的api文档。java中的javadoc,perl中的pod2man。比拟之下,php之前仿佛缺少响应的东西,不外,跟着phpdoc的不休完美,这类场合排场已大大改不雅。

在第一篇pear的编码划定规矩中有一条,pear法式中的正文应当可以被phpdoc转换。因而可知,phpdoc在pear中的感化可不小。明天,咱们将具体会商phpdoc,这个优异的pear法式。

1. 甚么是phpdoc
PHPDoc是PEAR上面的一个十分优异的模块,它的方针是完成相似javadoc的功效,可觉得你的代码疾速生成具有互相参照,索引等功效的API文档。假如你利用过javadoc生成的文档(如jdk的文档),你会十分清晰,假如你没有效过,那末上面是一个phpdoc生成它本人的文档页面的截图:






从图上可以晓得,phpdoc生成的文档和JAVADOC很类似,它有多种的索引体例:
Packageindex:这是依照模块来索引
Classtree:这是依照你的php类的承继关系,可以生成一个树状的索引
Modulegroups:这是依照模块划分
Elementlist:这是你的一切元素(类,办法,进程/函数,变量)的字母按次的索引

2. phpdoc的布局及功效
因为phpdoc自己也是合适pear的使用法式,咱们起首懂得一下它的布局。phpdoc是全体采取OOP的思惟来编写的,这也是PEAR所保举的体例,phpdoc的任务道理:

phpdoc扫描指定目次上面的php源代码,扫描个中的关头字,截取需求剖析的正文,然后剖析正文中的公用的tag,生成xml文件,接着依据已剖析完的类和模块的信息,创立响应的索引,生成xml文件
关于生成的xml文件,利用定制的模板输入为html文件。

从设计下去说,phpdoc利用了2个超类:PhpdocObject和PhpdocError。这是全部PHPDOC的根基类,这类体例也是PEAR所保举的,也就是说当你编写你本人的使用框架的时分,最好可以有一个根基的超类,而其他的子类或是功效类都有一个配合的先人。在扫描源代码过程当中,PHPDOC利用的是相似GREP的模式,并没有象咱们凡是想的那样,利用正则表达式来完成,依据作者的注释,他已经测验考试过利用正则表达式,然而资本的占用和处置速度都很难使人写意,因而采取了这类十分规的模式,详细的完成有乐趣的读者可以参看源代码。我以为PHPDOC使人写意的另外一方面是其剖析了局是以XML模式保留的,如许就意味着其他的使用法式很轻易可以同享这个数据,同时PHPDCO也供应了响应的接口,你可以完成这个接口,把API文档生成其他的模式,好比PDF,LATEX,WORD等等。今朝,PHPDOC的剖析了局可以以HTML模式体现,今后能够会有更多的模式。即便是HTML模式,因为利用了模板机制(他利用了PEAR的IT和ITX模块来完成),你可以很便利地定制成你本人需求的作风,

3. PHPDoc基本
PHPDoc是从你的源代码的正文中生成文档,因而在给你的法式做正文的进程,也就是你编制文档的进程。

从这一点上讲,PHPdoc促使你要养成优秀的编程习气,尽可能利用标准,明晰文字为你的法式做正文,同时多几何少也防止了过后编制文档和文档的更新分歧步的一些成绩。

编制合适PHPDoc标准的正文长短常主要的,把握了这一点,根基上就能够使用PHPDoc为你任务了。

正文在PHPDoc平分为文档正文和非文档正文

3.1 文档正文
文档正文实践上是一些特别模式的多行正文,通常为放在你需求正文的特定的关头字(这些关头字是指将会被phpdoc剖析的那些关头字,相干的关头字列表请参看前面第4节的申明)后面。上面是一个文档正文的例子:


/**
* Common base class of all phpdoc classes (简述,用在索引列表中)
*
* As a kind of common base class PhpdocObject holds
* configuration values (e.g. error handling) and debugging
* methods (e.g. introspection()). It does not have a constructor,
* so you can always inheritig Phpdoc classes from this
* class without any trouble. (具体的功效描写)
*
* @author Ulf Wendel
* @version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $
* @package PHPDoc (文档标志)
*/
class PhpdocObject {
.....
}



以上的文档正文将会生成以下的文档:
<b>PhpdocObject</b>

PhpdocObject

Common base class of all phpdoc classes


<b>private class PhpdocObject </b>

Common base class of all phpdoc classes
As a kind of common base class PhpdocObject holdsconfiguration values (e.g. error
handling) and debuggingmethods (e.g. introspection()). It does not have a
constructor,so you can always inheritig Phpdoc classes from thisclass without any trouble.

Authors Ulf Wendel <ulf.wendel@phpdoc.de>
Version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $




3.2 非文档性正文
假如你的正文没有放在那些phpdoc指定的关头字后面,那末phpdoc以为你所作的这些正文是属于非文档正文,将不会被phpdoc所剖析,也不会呈现在你发生的api文傍边。

3.3 若何书写你的文档性正文
从3.1 咱们可以看到,一个文档性的正文,是由3个局部构成的,分离是:功效简述区,功效具体申明区,文档标志区。

起首,第一行是一个正文入手下手的标记"/**",然后是回车,从第2行入手下手就是功效简述区,功效简述区是以缩进的"*"入手下手的,在简述的注释和这个"*"号之间用空格分隔(注重,在文档中,都是以*入手下手,而且这些*坚持对齐的缩进格局)。功效简述的注释通常为长篇大论地申明这个类,办法或函数的功效,功效简述的注释在生成的文档中将显示在索引区。

在功效简述区前面是一个空的正文行,用来朋分简述区和具体申明区。功效具体申明区也是以缩进的'*"来引诱的,这局部次要是具体申明你的API的功效,用处,假如能够,也能够有效法举例等等。在这局部,你应当侧重说明你的API函数或办法的凡是的用处,用法,而且指明是不是是跨平台的(假如触及到),关于战争台相干的信息,你要和那些通用的信息区分看待,凡是的做法是另起一行,然后写出在某个特定平台上的注重事项或是出格的信息,这些信息应当足够,以便你的读者可以编写响应的测试信息,好比界限前提,参数局限,断点等等。

在功效具体申明区前面,是空白的正文行,然后是文档标志区,你可以在这些书写相干的文档标志(这些文档标志的用法请参考前面的第4节),指明一些手艺上的细节信息,最次要的是挪用参数类型,前往值极为类型,承继关系,相干办法/函数等等。多个文档标志应当利用不异的缩进,构成一个"标志块",便于浏览和剖析。

在文档标志区上面的一行就是正文停止行"*/",注重,在正文停止标志*/前面应当直接跟一个回车,不要别的附加其他的器材,不然能够形成PHPDOC剖析失足。

以上就是书写一个文档性正文的根基办法,上面咱们会商一下书写文档时的标准和技能。

3.4 文档书写指南
在你描写你的代码的用处或是功效的时分,最好可以遵守大多半人的习气,浅显地讲就是"你告知我的信息恰是我想要晓得的"。为此,这里将引见一些书写文档正文的技能和标准,但愿可以对你有所匡助:

利用 <code> 来标记关头字和定名及相干的代码。假如在文档中需求援用一些关头字,变量名,或是你要给出一些代码的例子,那末你最好利用<code></code>来将这些关头字,变量名,代码片断和你的文档分离隔,如许,读者浏览的时分,将会晓得,这些将是运转的代码,关头字而不是你的描写性的言语。
利用复杂,明白的言语,防止冗杂,庞杂,流畅的长句来描写。特别是在功效简述,参数申明等索引局部中,尽可能利用复杂分明的言语提醒次要的信息,把其他的细节放在具体申明局部去论述。假如你利用英语,建议利用短语而纷歧定是句子。
假如利用英语,建议利用第3人称双数的模式来讲明
在给办法,函数申明的时分,你需求申明的是这个办法"作了甚么",而不是"怎样做"。因而,建议你的申明是以动词入手下手,好比"前往纪录数","删除给定的纪录"等等。
当你援用的某个对象或变量是从以后的类中创立的,那末利用 "this" 取代 "the" 来指代谁人对象或是变量
防止废话,空话,关于你所要给出的API,在你的API前面要有它的功效描写,是其可以"自成文档"。所谓的废话,空话是指,你的描写不是功效描写,而只是API称号的复杂反复和枚举,或是用另外一个API来注释这个API,到头来,你的读者也不晓得你所要表达的内容本色。你的描写,应当是那些从你的类名,办法名,或是函数名看不到的增补的信息,而不是把你的API称号再反复一遍。良多人能够良多人(包含我)不知不觉中就犯了这个毛病,上面是一个例子:
/**
* 设置用户纪录集
*
* @param text 给定的表名
*/
function set_user_record($table) {




你从下面这段正文中可以晓得甚么?因而,这段正文实践上是空话,由于你从函数称号上是可以看出的,上面是改善后的:
/**
* 翻开体系用户表并设置为以后用户纪录集,此纪录集将用于随后相干用户数据更新操作的缺省纪录集。假如掉败则抛出一个数据库毛病。
*
* @param text 要翻开的体系用户表的表名。
*/
function set_user_record($table) {




恰当地利用链接。为你文档中援用的API称号(包含你的其他类及办法,PHP的函数等)添加恰当的链接是很受接待的:你可使用@link标志来添加到相干的API的链接,不外,你没有需要为文档中援用的一切的API都添加毗连,如许会很不雅观,这里有一个复杂的尺度:假如用户在这个中央看到某个API,的确但愿要去点击以便获得更多信息,如许有助于他们去了解你的文档,而且即便添加了链接,只在它第一呈现的是时分添加,没有需要反复添加不异的LINK。
因为PHPDOC的功效限制,一个PHP文件只界说一个类或模块,不要把类和模块的界说放在统一个文件里,不然PHPDOC能够没法任务,最少今朝版本是如许。假如你的框架利用OOP来构建,应防止同时利用模块或模块组;同时应当细心计划你的使用布局,你的使用框架应当是一个相似树型的布局,顶层的分支不要太多,例如你可以设计2个超类,分离是作为正常使用和毛病处置的超类,其他的都从这2个类派生出来。
4. PHPDoc关头字及文档标记
4.1 关头字
class 、function 、var 、include (include_once, require, require_once) 、define

在以上这些关头字后面所做的正文,都被以为是文档性正文。

4.2 文档标志
申明:利用局限是指该标志可以用来润色的关头字,或其他文档标志
@abstract 利用局限:class, function, var
申明以后类是一个笼统类。

正文:从PHP言语角度来讲,它其实不象JAVA,C++那样,撑持笼统类这个概念。也没有响应的关头字来润色某个类是笼统类。因为PHPDOC实践上大局部是自创了JAVADOC的做法,因而良多文档标志也是直接从JAVADOC中因循过去,如abstract,access,final等等。固然这些特征没有从言语级别失掉撑持,不外从利用者角度来遵守这些特征,还是值得保举的。

举例:
/**
* 这是一个绘五星图案的笼统类.
* @abstract
*/
class paint_start {
/**
* 绘制数目
* @abstract
*/
var $number;
/**
* 绘制五星图案
* @abstract
*/
function paint() {
;
}
}


@access (public|private) 利用局限:class, function, var, define, module

指明这个变量、类、函数/办法的存取权限。假如你的函数是外部利用,你应当指明它为private,如许的优点是,即便PHP不克不及禁止其他的人利用你的公有数据,然而最少你向你的用户转达如许的信息,这是一个公有的函数,因而不包管在未来的版本中仍存在;关于利用者而言,暗示为@private的数据和办法,你不该该直接利用,即便你可以如许做。

举例:
/**
* 这是一个绘五星图案的笼统类.
* @abstract
* @access public
*/
class paint_start {

/**
* 绘制数目
* @abstract
* @access private
*/
var $number;

/**
* 绘制五星图案
* @abstract
* @access public
*/
function paint() {
;
}

}


@author Name [<email>] [, ...] 利用局限:class, function, var, define, module, use

指明作者信息,顺次是作者姓名,email地址,其他的通信信息。假如有多个作者,依照其前后次第,利用多个@author顺次列出:

* @author Night Sailer <night@hotmail.com>
* @author Lee Tester <tester@gnome.org>
@brother (function()|$variable) 利用局限:class, function, var, define, module, use
@sister (function()|$variable) 利用局限:class, function, var, define, module, use

指出兄弟类、函数或是变量.这些函数、类、变量等有类似的信息和并完成不异的功效。好比,挪用和前往的参数的个数和类型不异,完成的功效也一样。这类情形,你可使用@brother 或 @sister指明它的兄弟函数,不必在反复书写函数的功效等信息了。

举例:
/**
* 这是一个绘五星图案的笼统类.
* @abstract
* @access public
*/
class paint_start {

/**
* 绘制数目
* @abstract
* @access private
*/
var $number;

/**
* 绘制五星图案
* @abstract
* @access public
*/
function paint() {
;
}

/**
* @brother paint()
*/
function draw() {
;
}

}




@const label 利用局限:define
指明常量
这个标志实践上是用来讲明php的define关头字界说的常量。

@copyright description 利用局限:class, function, var, module, define, use
指明版权信息。

@deprec label 利用局限:class, function, var, module, define, use
指明不保举或是放弃的信息.

假如你的某个函数或办法,已被新的函数办法替换,或是已放弃,不但愿读者持续利用。那末你可使用这个标记告知读者,这个函数只是为了坚持兼容性而保存的,它不被保举利用,假如它已被其他函数替换,也要指出这个替换者。

例子:
/**
* 过时的类
*
* @deprec 1.5-2000/12/06
* @access public
*/
function dontUseMeAnyMore() {
print "Don't use me any more. I have been deprecated.";
}




@exclude label 利用局限:class, function, var, module, define, use
指明以后的正文将不停止剖析,不呈现在文挡中

@final 利用局限:class, function, var
指明这是一个终究的类、办法、属性,制止派生、修正。
举例:
/**
* 圆周率
* @final
*/
var $PI = 3.1415926;




@global (object objecttype|type) [$varname] 利用局限:function
指明在此函数中援用的全局变量
举例:
/**
* Simuliert include_once in PHP 3.
*
* @global array $__used_files 已include的文件列表
* @access public
*/
function include_once($filename) {
global $__used_files;

if (!isset($__used_files["include_once"][$filename])) {
$__used_files["include_once"][$filename] = true;
include($filename);
}
}




@include description 利用局限:use
指明包括的文件的信息。
举例:
/**
* 笼统画图类的界说.
*
* @includeFunction: _require_
*/
require("abstract.php");




@link URL description 利用局限:class, function, var, module, define, use
界说在线毗连,如下面3.4中讲到的,你可使用@link添加恰当的在线链接。
例如:@link http://www.phpdoc.de/ PHPDoc Home

@magic description
这个标志在phpdoc中没有申明,详细用法如今仍不清晰

@module label 利用局限:module
界说归属的模块信息,label是模块的名字,具有不异的模块名字的函数在索引分类中将被组合在一同。假如你没有利用OOP的思惟来编写PEAR代码,那末建议你利用这个标志把相干的函数归集到响应的模块上面,如许你的全体的框架不至于过于零星和凌乱。

@modulegroup label 利用局限:module
界说归属的模块组 label是这个模块组的名字,假如你的使用法式的模块良多,你可以把分歧的模块依照逻辑功效的分歧,划分红响应的模块组,如许,你的使用框架可以有对照明晰的逻辑关系。这是关于没有利用OOP编程的来讲的,假如利用OOP的思惟,没有需要利用模块组的概念,由于直接利用"包-超类--基类--子类"的模式来表现你的框架布局要比利用"包-模块组-模块"的模式好的多。

@package label 利用局限:class, module
界说归属的包的信息,label 是这个包的名字。不异的包的名字的类在终究文档索引中将被分在一同。实践上,包还可以了解为分歧的名字空间,固然PHP没着名字空间的概念,然而你可以把相干的类、模块都归属于统一个包,如许,相当于组织了一个名字空间,固然,你的使用框架能够会有分歧的包,惋惜的是,这类情形下从语法上是得不到名字空间这类包管的,你只能经由过程工资地去防止分歧的包的函数或类重名。

@param (object objecttype|type) [$varname] 利用局限:function
界说函数或办法的参数信息。这是最常利用的文档标志了。

ojecttype 是对象的类名,type 指出这个参数的类型,它可所以以下类型:

string 该参数是一个字符型变量。
array 该参数是一个数组。
integer 该参数是一个数值型。
integer (octal) 该参数是一个数值型,而且是依照八进制体例寄存。
integer (hexadecimal) 该参数是一个数值型,而且是依照十六进制体例寄存。
boolean 该参数是一个布尔型。
mixed 该参数的类型是可变的,可以下面几品种型的组合。不外,在随后的申明中普通要申明可以承受的变量的类型。
$varname 是形参的称号
是关于参数的申明。
假如函数承受的是多个参数,那末要依照从左到右,顺次用@param对齐列出,以下面所示:
*
* @param array $tags array of tags returned by getTags
* @param array $data array where the allowed tags and their values are copied to
* @param array $allowed array of allowed (recognized) tags




@return (object objecttype|type) [$varname] 利用局限:function
界说函数或办法的前往信息。
前往信息的类型同@param一样,$varname是前往变量的称号,无关紧要。分歧的是@return只要一个,不会呈现多个@return

@see (function()|$varname|((module|class)::)(function()|$varname)) [, ...] 利用局限:class, function, var, module, define, use
界说需求参考的函数、变量,并到场响应的超等毗连。这也是较经常使用的标志。关于相干的函数,变量,你可使用@see来增添一个到相干函数和变量的链接。多个相干的函数、变量写在一行,两头用逗号来分隔。
参考的函数、变量假如是以后类或模块的,那末你可以直接写函数、或变量的名,假如是函数那末要在函数名前面加上括号(),变量名要加上$。需求注重的,这里所谓的变量名也应当是你用@var来讲明过的,不然,phpdoc将没法找到相干的参照而报错。
假如你想援用其他类或其他模块的函数或是变量,那末,你可以在函数名、变量名后面加上类或模块的名字作为局限唆使,两头用::来分隔。

上面是一些例子:
@see $run_time,$idle_time,$begin_time,$end_time
@see getRuntime(), getIdletime(),getBegintime(),getEndtime()
@see TIME::$run_time, TIME::getBegintime()

@since label 利用局限: class, function, var, module, define, use
指明该api函数或办法是从哪一个版本入手下手引入的。

@static 利用局限:class, function, var
指明变量、类、函数是静态的。

@throws exception [, exception] 利用局限: function
指明此函数能够抛出的毛病异常,极为产生的情形
假如你意料到在这个函数中有发生异常的前提,那末你可使用@throws标志来讲明这些异常是甚么,甚么情形下发生异常。好比,读取磁盘文件失足,没法毗连数据库,收集毗连超时或是在一些情形下,你"居心"抛出的异常等等。

@todo 利用局限:class, function, module, use
指明应当改善或没有完成的中央

@var (object objecttype|type) [$varname] 利用局限:var
界说申明变量/属性。
object objecttype|type 界说你的变量的类型,同@param一样
$varname 该变量的名字,你可以从其他中央利用@see来援用这个名字
description 对变量的描写

@version label 利用局限:class, function, module, use
界说版本信息.
你固然可以本人手工写这些版本信息,不外PEAR保举你利用CVS的$Id标志来主动标示你的版本信息。模式以下:

@version $Id
如许,当你checkout的时分,CVS主动会扩大成: @version $Id: PhpdocParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp

5. 生成文档
5.1 装置PHPDOC
装置PHPDOC很复杂,实践上由于它已伴同PHP 4.05一同宣布了,所以假如你的PHP是4.05,那末在PEAR目次上面会发明PHPDOC这个模块.假如你没有发明,你可以从PHPDOC的CVS取得一份最新的源码.

5.2 运转PHPDOC
运转PHPDOC需求做一些筹办任务,起首要调剂你的PHP.INI的参数,

由于PHPDOC运转的工夫比普通的PHP使用要长,极可能会超越你在PHP.INI中界说的最大运转工夫(缺省是30秒),依据作者的建议:PIII,60秒,120秒PII,240秒MMX200,480秒假如设置装备摆设更低的话。假如呈现超时,你可以本人恰当延伸这些数值。

在php.ini中修正:
;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 480
memory_limit = 8388608




假如你不肯意或没有修正php.ini的权限,那末你可使用set_time_limit()函数来设置这个工夫,利用办法: set_time_limit(480); 设置从此点入手下手,运转480秒后才超时。将这个函数加在index.php中,就能够和修正php.ini到达一样的后果。

其次,你要修正phpdoc目次上面的index.php文件:
// Directory with include files
define("PHPDOC_INCLUDE_DIR", "c:/www/apache/doc/");


将"c:/www/apache/doc/修正成你的phpdoc的目次
// Important: set this to the Linebreak sign of your system!
define("LINEBREAK", "\r\n");
这是界说换行的标记,DOS上面是换行+回车,UNIX上面只是回车就能够。

上面,为你的要生成文档的使用法式做一些定制任务:
// Sets the name of your application.
// The name of the application is used e.g. as a page title
$doc->setApplication("PHPDoc");

setApplication()用来设置你的使用法式的称号,将PHPDOC交换成你使用法式的名字。

// directory where your source files reside:
$doc->setSourceDirectory(PHPDOC_INCLUDE_DIR);

setSourceDirectory()设置你的使用法式的PHP源文件地点的目次,将PHPDOC_INCLUDE_DIR交换成你实践的目次。

// save the generated docs here:
$doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/");

setTarget()设置你的API文档寄存的目次,PHPDOC将在这个目次上面生成XML及HTML文件。将PHPDOC_INCLUDE_DIR."apidoc/"交换成你本人的目次。

// use these templates:
$doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/");

setTemplateDirectory()设置HTML所利用的模板的目次。假如你需求利用定制的模板,可使用这个函数设置你本人的模板文件地点的目次。

// source files have one of these suffixes:
$doc->setSourceFileSuffix( array ("php", "inc") );

setSourceFileSuffix()用来设置需求剖析的PHP源文件的扩大名,假如你利用了其余扩大名,需求在这里添加,好比假如你有之前的php3文件,需求添加:
$doc->setSourceFileSuffix( array ("php", "inc","php3") );


如许,根基的定制任务就完成了,如今你可以在阅读器中运转index.php,呈现了接待信息后,就是入手下手剖析文档了.依据机械的情况和所剖析的源代码文件的数目分歧,文档剖析进程所需的工夫也不会不异.文档剖析停止后,阅读器会显示FINISH的字样,标明剖析完成,你可以在方才指定的目次上面找到剖析了局,包含HTML和XML文件.

5.3 适用东西
经由过程PHPDOC的INDEX.PHP固然可以发生文档,然而究竟不是那末便利,这里我给出了一个本人写的shell法式 makeapidoc ,你可以用它来便利的发生你的API文档,不必每次都要修正,也不必非要启动阅读器来履行。

用法以下:makeapidoc -t 你的使用法式的题目 -s 源法式目次 -d 生成文档寄存目次

在利用之前,先修正上面2行:
PHPDOC_DIR="/usr/local/lib/php/pear/PHPDoc" # windows: c:/php/pear/PHPDoc
PHPBIN="/usr/local/bin/php" #windows: c:/php/php.exe
PHPDOC_DIR是PHPDOC的目次,PHPBIN是PHP可履行文件的途径。


这个法式实践上是把PHP作为一个SHELLSCRIPT来利用了,不外是嵌在BASH中利用,实践上PHP完整可以做为通俗的SHELL剧本一样运转,只需加上 -q 参数,如许就不打印HTTP HEADER了。


6. 进阶:定制输入的文档
假如你以为缺省的PHPDOC发生的HTML文档不敷雅观,你想做进一步的改善,好比你想把一些正文换成中文或是其他的文字,你想到场你的LOGO,或是你的接洽体例,换成一个大度的后台图案,有无办法可以作到?谜底是固然可以,而且十分复杂.

PHPDOC在输入HTML格局的API文档的时分,利用的是PEAR的IT,ITX模块,这是相似PHPLIB的TEMPLETE.CLASS的PEAR模块,因而,你可以便利地定制和修正缺省的模板来为你所用.

咱们先看看PHPDOC/renderer/html/templates: class.html classtree.html elementlist.html frame_packageelementlist.html
frame_packagelist.html module.html modulegroup.html packagelist.html phpdoc.css warnings.html xmlfiles.html

你会看到下面的这些文件,没错,这些就是PHPDOC用来发生API HTML的模板,如今你可以用你的编纂器来修正这些模板了,这里给出根基的修正准绳:

关于用{}圈起来的标志,这些是一些变量的标志,在运转时辰,PHPDOC将会用实践的变量值交换到响应的地位.因而,你务需要保存全体的变量标志,不然运转时将会失足.
你要注重<!--Begin Xxx-loop --><!--End Xxx -loop-->之类带LOOP的正文,在这2个标志两头的局部,将会用于轮回输入,所以,你在设计模板时要思索到轮回利用,是不是会损坏你页面的雅观,最复杂的好比:假如轮回的局部是在一个表格内,你要用<tr>用来分隔各轮回挪用的局部,同时应当包管各个<TD></TD>是婚配封闭的.
当你修正的中央不大,你也能够直接修正款式表phpdoc.css的内容,如许也能够到达你请求的后果
你可以把模板寄存在分歧的目次,经由过程setTemplateDirectory()设置分歧的模板途径,就能够生成分歧格局的API文档

7. 参考资本

PHPDOC HOME
PHPDOC CVS
可以在书上很方便地做标记,及时记下自己的心得体会。

谁可相欹 发表于 2015-2-4 13:09:12

说点我烦的低级错误吧,曾经有次插入mysql的时间 弄了300年结果老报错,其实mysql的时间是有限制的,大概是到203X年具体的记不清啦,囧。

再见西城 发表于 2015-2-5 09:45:25

学好程序语言,多些才是王道,写两个小时代码的作用绝对超过看一天书,这个我是深有体会(顺便还能练打字速度)。

变相怪杰 发表于 2015-2-11 08:39:14

实践是检验自己会不会的真理。

冷月葬花魂 发表于 2015-2-12 00:03:04

作为一个合格的coder 编码的规范是必须,命名方面我推崇“驼峰法”,另外就是自己写的代码最好要带注释,不然时间长了,就算是自己的代码估计看起来都费事,更不用说别人拉。

活着的死人 发表于 2015-2-14 03:40:45

Apache不是非得用80或者8080端口的,我刚开始安得时候就是80端口老占用,就用了个 81端口,结果照常,就是输localhost的时候,应该输入为 localhost:81

第二个灵魂 发表于 2015-2-25 15:01:28

如果你可以写完像留言板这样的程序,那么你可以去一些别人的代码了,

因胸联盟 发表于 2015-3-7 05:43:57

这些都是最基本最常用功能,我们这些菜鸟在系统学习后,可以先对这些功能深入研究。

不帅 发表于 2015-3-9 20:45:58

对于初学者来说不推荐去拿钱买的。当然如果一个网站你经常去用,而且里面的资料也比较有用,最好还是买个会员比较好,毕竟那些也是别人的工作成果。

再现理想 发表于 2015-3-17 01:07:58

做为1门年轻的语言,php一直很努力。

山那边是海 发表于 2015-3-17 18:27:51

我学习了一段时间后,我发现效果并不好(估计是我自身的问题)。因为一个人的精力总是有限的,同时学习这么多,会导致每个的学习时间都得不到保证。

小妖女 发表于 2015-3-24 19:27:38

这些都是最基本最常用功能,我们这些菜鸟在系统学习后,可以先对这些功能深入研究。

兰色精灵 发表于 2015-4-6 14:13:03

要进行开发,搭建环境是首先需要做的事,windows下面我习惯把环境那个安装在C盘下面,因为我配的环境经常出现诡异事件,什么事都没做环境有的时候就不能用啦。

海妖 发表于 2015-4-9 17:41:12

我要在声明一下:我是个菜鸟!!我对php这门优秀的语言也是知之甚少。但是我要在这里说一下php在网站开发中最常用的几个功能:

金色的骷髅 发表于 2015-4-16 16:38:24

这些都是最基本最常用功能,我们这些菜鸟在系统学习后,可以先对这些功能深入研究。

简单生活 发表于 2015-4-22 04:00:45

当留言板完成的时候,下步可以把做1个单人的blog程序,做为目标,

灵魂腐蚀 发表于 2015-4-22 04:57:37

你很难利用原理去编写自己的代码。对于php来说,系统的学习我认为还是很重要的,当你有一定理解后,你可你针对某种效果研究,我想那时你不会只是复制代码的水平了。

分手快乐 发表于 2015-4-29 04:24:20

遇到出错的时候,我经常把错误信息直接复制到 google的搜索栏,一般情况都是能搜到结果的,不过有时候会搜出来一大片英文的出来,这时候就得过滤一下,吧中文的弄出来,挨着式方法。

小魔女 发表于 2015-6-4 21:13:12

其实也不算什么什么心得,在各位大侠算是小巫见大巫了吧,望大家不要见笑,若其中有错误的地方请各位大虾斧正。
页: [1]
查看完整版本: PHP编程:PEAR:利用PHPDoc轻松创立你的PEAR文档...