关于PHPDocument 代码注释规范的总结


Posted in PHP onJune 25, 2013

1. 安装phpDocumentor(不推荐命令行安装)
在http://manual.phpdoc.org/下载最新版本的PhpDoc
放在web服务器目录下使得通过浏览器可以访问到
点击files按钮,选择要处理的php文件或文件夹
还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
然后点击output按钮来选择生成文档的存放路径和格式.
最后点击create,phpdocumentor就会自动开始生成文档了。

2.如何写PHP规范注释
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。
@access 该标记用于指明关键字的存取权限:private、public或proteced 使用范围:class,function,var,define,module
@author 指明作者
@copyright 指明版权信息
@const 使用范围:define 用来指明php中define的常量
@final 使用范围:class,function,var 指明关键字是一个最终的类、方法、属性,禁止派生、修改。
@global 指明在此函数中引用的全局变量
@name 为关键字指定一个别名。
@package 用于逻辑上将一个或几个关键字分到一组。
@abstrcut 说明当前类是一个抽象类
@param 指明一个函数的参数
@return 指明一个方法或函数的返回值
@static 指明关建字是静态的。
@var 指明变量类型
@version 指明版本信息
@todo 指明应该改进或没有实现的地方
@link 可以通过link指到文档中的任何一个关键字
@ingore 用于在文档中忽略指定的关键字

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

能够被phpdoc识别的关键字:
Include
Require
include_once
require_once
define
function
global
class

3. 规范注释的php代码 :
<?php
/**
* 文件名(sample2.php)
*
* 功能描述(略)
*
* @author steve <https://3water.com>
* @version 1.0
* @package sample2
*/
/**
* 包含文件
*/
include_once 'sample3.php';
/**
* 声明全局变量
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* 声明全局常量
*/
define('NUM', 6);
/**
* 类名
*
* 类功能描述
*
* @package sample2
* @subpackage classes(如果是父类 就添加)
*/
class myclass {
/**
* 声明普通变量
*
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* 创建构造函数 {@link $firstvar}
*/
function myclass() {
$this->firstvar = 7;
}
/**
* 定义函数
*
* 函数功能描述
*
* @global string $_myvar
* @staticvar integer $staticvar
* @param string $param1
* @param string $param2
* @return integer|string
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
}
?>

PHP 相关文章推荐
php5数字型字符串加解密代码
Apr 24 PHP
php 三维饼图的实现代码
Sep 28 PHP
关于PHP5 Session生命周期介绍
Mar 02 PHP
php中定时计划任务的实现原理
Jan 08 PHP
获取PHP警告错误信息的解决方法
Jun 03 PHP
php生成随机密码自定义函数代码(简单快速)
May 10 PHP
PHP实现文件上传与下载实例与总结
Mar 13 PHP
全面解读PHP的Yii框架中的日志功能
Mar 17 PHP
thinkphp5.1 文件引入路径问题及注意事项
Jun 13 PHP
php实现算术验证码功能
Dec 05 PHP
php根据命令行参数生成配置文件详解
Mar 15 PHP
php字符串过滤strip_tags()函数用法实例分析
Jun 24 PHP
解析php中获取系统信息的方法
Jun 25 #PHP
解析PHP对现有搜索引擎的调用
Jun 25 #PHP
手把手教你打印出PDF(关于fpdf的简单应用)
Jun 25 #PHP
解析如何修改phpmyadmin中的默认登陆超时时间
Jun 25 #PHP
关于Sphinx创建全文检索的索引介绍
Jun 25 #PHP
使用Sphinx对索引进行搜索
Jun 25 #PHP
深入PHP许愿墙模块功能分析
Jun 25 #PHP
You might like
10 个经典PHP函数
2013/10/17 PHP
php中利用explode函数分割字符串到数组
2014/02/08 PHP
四种php中webservice实现的简单架构方法及实例
2015/02/03 PHP
Laravel 5 框架入门(一)
2015/04/09 PHP
php实现的RSS生成类实例
2015/04/23 PHP
原生JS实现Ajax通过GET方式与PHP进行交互操作示例
2018/05/12 PHP
基于jquery实现的可以编辑选择的下拉框的代码
2010/11/19 Javascript
有关javascript的性能优化 (repaint和reflow)
2013/04/12 Javascript
jquery中使用循环下拉菜单示例代码
2014/09/24 Javascript
Javascript实现div层渐隐效果的方法
2015/05/30 Javascript
基于jQuery实现中英文切换导航条效果
2016/09/18 Javascript
基于JS实现checkbox全选功能实例代码
2016/10/31 Javascript
全面总结Javascript对数组对象的各种操作
2017/01/22 Javascript
js获取元素下的第一级子元素的方法(推荐)
2017/03/05 Javascript
Angularjs中ng-repeat的简单实例
2017/08/25 Javascript
浅谈Vue2.0父子组件间事件派发机制
2018/01/08 Javascript
vue2.0 根据状态值进行样式的改变展示方法
2018/03/13 Javascript
nodeJs项目在阿里云的简单部署
2020/11/27 NodeJs
[40:03]DOTA2上海特级锦标赛主赛事日 - 1 败者组第一轮#1EHOME VS Archon
2016/03/02 DOTA
基于Python_脚本CGI、特点、应用、开发环境(详解)
2017/05/23 Python
python3实现163邮箱SMTP发送邮件
2018/05/22 Python
基于Python爬取fofa网页端数据过程解析
2020/07/13 Python
Python的Tqdm模块实现进度条配置
2021/02/24 Python
CSS3悬停效果案例应用
2012/11/21 HTML / CSS
Nike德国官网:Nike.com (DE)
2018/11/13 全球购物
eDreams葡萄牙:全球最大的在线旅行社之一
2019/04/15 全球购物
大学生职业规划书的范本
2014/02/18 职场文书
公司门卫岗位职责范本
2014/07/08 职场文书
党的群众路线教育实践活动整改方案
2014/10/28 职场文书
2014七年级班主任工作总结
2014/12/05 职场文书
婚姻出轨保证书
2015/05/08 职场文书
地心历险记观后感
2015/06/15 职场文书
医德医风学习心得体会
2016/01/25 职场文书
Golang二维切片初始化的实现
2021/04/08 Golang
MySQL 使用自定义变量进行查询优化
2021/05/14 MySQL
IDEA中sout快捷键无效问题的解决方法
2022/07/23 Java/Android