码迷,mamicode.com
首页 > Web开发 > 详细

PHPDoc PHP注释的标准文档(翻译自Wiki)

时间:2014-06-03 17:07:59      阅读:501      评论:0      收藏:0      [点我收藏+]

标签:c   style   class   blog   code   a   

文档注释,无非“//”和“/**/”两种 ,自己写代码,就那么点,适当写几句就好了;但是一个人总有融入团队的一天,团队的交流不是那几句注释和一张嘴能解决的,还需要通用的注释标准。

PHPDoc是PHP文档注释的一个标准,可以帮助我们在注释文档时有规范,查看别人的代码时更方便。下面的表格是我翻译的WIKI上的PHPDoc,个人英文水平有限,可以参照原文。

文档翻译自:http://en.wikipedia.org/wiki/Phpdoc

标记 用途 描述
@abstract   抽象类的变量和方法
@access public, private or protected 文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author 张三 <zhangsan@163.com> 文档作者
@copyright 名称 时间 文档版权信息
@deprecated version 文档中被废除的方法
@deprec   同 @deprecated
@example /path/to/example 文档的外部保存的示例文件的位置。
@exception   文档中方法抛出的异常,也可参照 @throws.
@global 类型:$globalvarname 文档中的全局变量及有关的方法和函数
@ignore   忽略文档中指定的关键字
@internal   开发团队内部信息
@link URL 类似于license 但还可以通过link找到文档中的更多个详细的信息
@name 变量别名 为某个变量指定别名
@magic   phpdoc.de compatibility
@package 封装包的名称 一组相关类、函数封装的包名称
@param 如 [$username] 用户名 变量含义注释
@return 如 返回bool 函数返回结果描述,一般不用在void(空返回结果的)的函数中
@see 如 Class Login() 文件关联的任何元素(全局变量,包括,页面,类,函数,定义,方法,变量)。
@since version 记录什么时候对文档的哪些部分进行了更改
@static   记录静态类、方法
@staticvar   在类、函数中使用的静态变量
@subpackage   子版本
@throws   某一方法抛出的异常
@todo   表示文件未完成或者要完善的地方
@var type 文档中的变量及其类型
@version   文档、类、函数的版本信息

原文截图:

bubuko.com,布布扣

PHPDoc注释实例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<?php
 /**
  * start page for webaccess
  *
  * PHP version 5
  *
  * @category  PHP
  * @package   PSI_Web
  * @author    Michael Cramer <BigMichi1@users.sourceforge.net>
  * @copyright 2009 phpSysInfo
  * @license   http://opensource.org/licenses/gpl-2.0.php GNU General Public License
  * @version   SVN: $Id: class.Webpage.inc.php 412 2010-12-29 09:45:53Z Jacky672 $
  * @link      http://phpsysinfo.sourceforge.net
  */
  /**
  * generate the dynamic webpage
  *
  * @category  PHP
  * @package   PSI_Web
  * @author    Michael Cramer <BigMichi1@users.sourceforge.net>
  * @copyright 2009 phpSysInfo
  * @license   http://opensource.org/licenses/gpl-2.0.php GNU General Public License
  * @version   Release: 3.0
  * @link      http://phpsysinfo.sourceforge.net
  */
 class Webpage extends Output implements PSI_Interface_Output
 {
     /**
      * configured language
      *
      * @var String
      */
     private $_language;
      
     /**
      * configured template
      *
      * @var String
      */
     private $_template;
      
     /**
      * all available templates
      *
      * @var Array
      */
     private $_templates = array();
      
     /**
      * all available languages
      *
      * @var Array
      */
     private $_languages = array();
      
     /**
      * check for all extensions that are needed, initialize needed vars and read config.php
      */
     public function __construct()
     {
         parent::__construct();
         $this->_getTemplateList();
         $this->_getLanguageList();
     }
      
     /**
      * checking config.php setting for template, if not supportet set phpsysinfo.css as default
      * checking config.php setting for language, if not supported set en as default
      *
      * @return void
      */
     private function _checkTemplateLanguage()
     {
         $this->_template = trim(PSI_DEFAULT_TEMPLATE);
         if (!file_exists(APP_ROOT.‘/templates/‘.$this->_template.".css")) {
             $this->_template = ‘phpsysinfo‘;
         }
          
         $this->_language = trim(PSI_DEFAULT_LANG);
         if (!file_exists(APP_ROOT.‘/language/‘.$this->_language.".xml")) {
             $this->_language = ‘en‘;
         }
     }
      
     /**
      * get all available tamplates and store them in internal array
      *
      * @return void
      */
     private function _getTemplateList()
     {
         $dirlist = CommonFunctions::gdc(APP_ROOT.‘/templates/‘);
         sort($dirlist);
         foreach ($dirlist as $file) {
             $tpl_ext = substr($file, strlen($file) - 4);
             $tpl_name = substr($file, 0, strlen($file) - 4);
             if ($tpl_ext === ".css") {
                 array_push($this->_templates, $tpl_name);
             }
         }
     }
      
     /**
      * get all available translations and store them in internal array
      *
      * @return void
      */
     private function _getLanguageList()
     {
         $dirlist = CommonFunctions::gdc(APP_ROOT.‘/language/‘);
         sort($dirlist);
         foreach ($dirlist as $file) {
             $lang_ext = substr($file, strlen($file) - 4);
             $lang_name = substr($file, 0, strlen($file) - 4);
             if ($lang_ext == ".xml") {
                 array_push($this->_languages, $lang_name);
             }
         }
     }
      
     /**
      * render the page
      *
      * @return void
      */
     public function run()
     {
         $this->_checkTemplateLanguage();
          
         $tpl = new Template("/templates/html/index_dynamic.html");
          
         $tpl->set("template", $this->_template);
         $tpl->set("templates", $this->_templates);
         $tpl->set("language", $this->_language);
         $tpl->set("languages", $this->_languages);
          
         echo $tpl->fetch();
     }
 }
 ?>

 

摘录自:http://www.cnblogs.com/picaso/archive/2012/10/04/2711435.html

PHPDoc PHP注释的标准文档(翻译自Wiki),布布扣,bubuko.com

PHPDoc PHP注释的标准文档(翻译自Wiki)

标签:c   style   class   blog   code   a   

原文地址:http://www.cnblogs.com/merryfreespace/p/3765074.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!