@access
@author
@copyright
@deprecated
@example
@const
@final
@filesource
@global
@ingore
@license
@link
@name
@package
@abstrcut
@param
@return
@static
@var
@version
@todo
@throws
{@link}
{@source}
a.注释必须是
/**
* 注释内容
*/
的形式
b.对于引用了全局变量的函数,必须使用glboal标记。
c.对于变量,必须用var标记其类型(int,string,bool…)
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可
f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。
g.必要的地方使用非文档性注释,提高代码易读性。
h.描述性内容尽量简明扼要,尽可能使用短语而非句子。
i.全局变量,静态变量和常量必须用相应标记说明
示例
<?php
/**
* Sample File 2, phpDocumentor Quickstart
*
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Beaver <cellog@php.net>
* @version 1.0
* @package sample
*/
//PHP code
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
?>
phpDocumentor官方网站
YII框架的注释范例:
/**
* CHttpSession提供了session级的数据管理和相关配置
*
* 开启session 调用 {@link open()};
* 完成和发送session数据,调用 {@link close()};
* 清除session,调用{@link destroy()}.
*
*
* CHttpSession can be used like an array to set and get session data. For example,
* <pre>
* $session=new CHttpSession;
* $session->open();
* $value1=$session['name1']; // get session variable 'name1'
* $value2=$session['name2']; // get session variable 'name2'
* foreach($session as $name=>$value) // traverse all session variables
* $session['name3']=$value3; // set session variable 'name3'
* </pre>
*
* The following configurations are available for session:
* <ul>
* <li>{@link setSessionID sessionID};</li>
* <li>{@link setSessionName sessionName};</li>
* <li>{@link autoStart};</li>
* <li>{@link setSavePath savePath};</li>
* <li>{@link setCookieParams cookieParams};</li>
* <li>{@link setGCProbability gcProbability};</li>
* <li>{@link setCookieMode cookieMode};</li>
* <li>{@link setUseTransparentSessionID useTransparentSessionID};</li>
* <li>{@link setTimeout timeout}.</li>
* </ul>
* See the corresponding setter and getter documentation for more information.
* Note, these properties must be set before the session is started.
*
* CHttpSession can be extended to support customized session storage.
* Override {@link openSession}, {@link closeSession}, {@link readSession},
* {@link writeSession}, {@link destroySession} and {@link gcSession}
* and set {@link useCustomStorage} to true.
* Then, the session data will be stored and retrieved using the above methods.
*
* CHttpSession is a Web application component that can be accessed via
* {@link CWebApplication::getSession()}.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @version $Id: CHttpSession.php 2497 2010-09-23 13:28:52Z mdomba $
* @package system.web
* @since 1.0
*/
class CHttpSession implements IteratorAggregate, ArrayAccess, Countable {
/**
* @var boolean whether the session should be automatically started when the session application component is initialized, defaults to true.
*/
public $autoStart = true;
private static $_instance = NULL;
/**
* Initializes the application component.
* This method is required by IApplicationComponent and is invoked by application.
*/
public function init() {
if ($this->autoStart) {
$this->open();
}
register_shutdown_function(array($this, 'close'));
}
/**
* Returns a value indicating whether to use custom session storage.
* This method should be overriden to return true if custom session storage handler should be used.
* If returning true, make sure the methods {@link openSession}, {@link closeSession}, {@link readSession},
* {@link writeSession}, {@link destroySession}, and {@link gcSession} are overridden in child
* class, because they will be used as the callback handlers.
* The default implementation always return false.
* @return boolean whether to use custom storage.
*/
public function getUseCustomStorage() {
return false;
}
/**
* Session open handler.
* This method should be overridden if {@link useCustomStorage} is set true.
* Do not call this method directly.
* @param string $savePath session save path
* @param string $sessionName session name
* @return boolean whether session is opened successfully
*/
public function openSession($savePath, $sessionName) {
return true;
}
// 截取了一部分
}
PHP命名规范
先了解下 1、什么是 驼峰命名法? 百度百科 2、大驼峰 与 小驼峰 的区别 ? 百度百科
1.类名:大驼峰命名法
2.类属性:
public、protected类型的,小驼峰命名法;
private类型的,下划线(_)开头,小驼峰命名法;
3.类方法:
public、protected类型的,小驼峰命名法;
private类型的,下划线(_)开头,小驼峰命名法;
4.类方法参数:小驼峰命名法;
5.函数:采用C GNU的惯例,所有的字母使用小写字母,使用下划线(_)分割单词;
6.函数参数:小驼峰命名法;
例如:
function some_bloody_function($userId, $userName) { }
7.常量:
所有字母都大写,使用下划线(_)分割单词;