Sivo 悉见

PHP Document 代码注释规范

匿名 · 更新于 2014/9/25

PHPDocument是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。

从这一点上讲，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。

在phpdocumentor中，注释分为文档性注释和非文档性注释。

所谓文档性注释，是那些放在特定关键字前面的多行注释，特定关键字是指能够被phpdoc分析的关键字，例如class，var等，具体的可参加附录1.

那些没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被phpdoc所分析，也不会出现在你产生的api文当中。
3.2如何书写文档性注释:

所有的文档性注释都是由/**开始的一个多行注释，在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息，使得其他人能够通过它知道这个关键字的具体用途，如何使用。 PhpDocumentor规定一个DocBlock包含如下信息：

1. 功能简述区

2. 详细说明区

3. 标记tag

文档性注释的第一行是功能描述区，正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束

在功能描述区后是一个空行，接着是详细说明区,. 这部分主要是详细说明你的API的功能，用途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。

之后同样是一个空白行，然后是文档的标记tag，指明一些技术上的信息，主要是最主要的是调用参数类型，返回值极其类型，继承关系，相关方法/函数等等。

关于文档标记，详细的请参考第四节:文档标记。

文档注释中还可以使用例如<b> <code>这样的标签，详细介绍请参考附录二。

下面是一个文档注释的例子

 

 

[php] view plaincopy
  1. 以下为引用的内容：  
  2.   
  3. /** 
  4. * 函数add,实现两个数的加法 
  5. * 
  6. * 一个简单的加法计算，函数接受两个数a、b，返回他们的和c 
  7. * 
  8. * @param int 加数 
  9. * @param int 被加数 
  10. * @return integer 
  11. */  
  12. function Add($a, $b) {  
  13. return $a+$b;  
  14. }  
  15.   
  16. 生成文档如下：  
  17. Add  
  18. integer Add( int $a, int $b)  
  19. [line 45]  
  20. 函数add,实现两个数的加法  
  21. Constants 一个简单的加法计算，函数接受两个数a、b，返回他们的和c  
  22. Parameters  
  23. ? int $a - 加数  
  24. ? int $b - 被加数  
  25. 5．文档标记：  
  26. 文档标记的使用范围是指该标记可以用来修饰的关键字，或其他文档标记。  
  27. 所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。  
  28. @access  
  29. 使用范围：class,function,var,define,module  
  30. 该标记用于指明关键字的存取权限：private、public或proteced  
  31. @author  
  32. 指明作者  
  33. @copyright  
  34. 使用范围：class，function，var，define，module，use  
  35. 指明版权信息  
  36. @deprecated  
  37. 使用范围：class，function，var，define，module，constent，global，include  
  38. 指明不用或者废弃的关键字  
  39. @example  
  40. 该标记用于解析一段文件内容，并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容  
  41. @const  
  42. 使用范围：define  
  43. 用来指明php中define的常量  
  44. @final  
  45. 使用范围：class,function,var  
  46. 指明关键字是一个最终的类、方法、属性，禁止派生、修改。  
  47. @filesource  
  48. 和example类似，只不过该标记将直接读取当前解析的php文件的内容并显示。  
  49. @global  
  50. 指明在此函数中引用的全局变量  
  51. @ingore  
  52. 用于在文档中忽略指定的关键字  
  53. @license  
  54. 相当于html标签中的<a>,首先是URL，接着是要显示的内容  
  55. 例如<a href=”http://www.baidu.com”>百度</a>  
  56. 可以写作 @license http://www.baidu.com 百度  
  57. @link  
  58. 类似于license  
  59. 但还可以通过link指到文档中的任何一个关键字  
  60. @name  
  61. 为关键字指定一个别名。  
  62. @package  
  63. 使用范围：页面级别的-> define，function，include  
  64. 类级别的->class，var，methods  
  65. 用于逻辑上将一个或几个关键字分到一组。  
  66. @abstrcut  
  67. 说明当前类是一个抽象类  
  68. @param  
  69. 指明一个函数的参数  
  70. @return  
  71. 指明一个方法或函数的返回指  
  72. @static  
  73. 指明关建字是静态的。  
  74. @var  
  75. 指明变量类型  
  76. @version  
  77. 指明版本信息  
  78. @todo  
  79. 指明应该改进或没有实现的地方  
  80. @throws  
  81. 指明此函数可能抛出的错误异常,极其发生的情况  
  82. 上面提到过，普通的文档标记标记必须在每行的开头以@标记，除此之外，还有一种标记叫做inline tag,用{@}表示，具体包括以下几种：  
  83. {@link}  
  84. 用法同@link  
  85. {@source}  
  86. 显示一段函数或方法的内容  
  87. 6．一些注释规范  
  88. a.注释必须是  
  89. /** 
  90. * XXXXXXX 
  91. */  
  92. 的形式  
  93. b.对于引用了全局变量的函数，必须使用glboal标记。  
  94. c.对于变量，必须用var标记其类型（int,string,bool...）  
  95. d.函数必须通过param和return标记指明其参数和返回值  
  96. e.对于出现两次或两次以上的关键字，要通过ingore忽略掉多余的，只保留一个即可  
  97. f.调用了其他函数或类的地方，要使用link或其他标记链接到相应的部分，便于文档的阅读。  
  98. g.必要的地方使用非文档性注释，提高代码易读性。  
  99. h.描述性内容尽量简明扼要，尽可能使用短语而非句子。  
  100. i.全局变量，静态变量和常量必须用相应标记说明  
  101. 7. 总结  
  102. phpDocumentor是一个非常强大的文档自动生成工具，利用它可以帮助我们编写规范的注释，生成易于理解，结构清晰的文档，对我们的代码升级，维护,移交等都有非常大的帮助。  
  103. 关于phpDocumentor更为详细的说明，可以到它的官方网站  
  104. http://manual.phpdoc.org/查阅  
  105. 8．附录  
  106. 附录1:  
  107. 能够被phpdoc识别的关键字：  
  108. Include  
  109. Require  
  110. include_once  
  111. require_once  
  112. define  
  113. function  
  114. global  
  115. class  
  116. 附录2  
  117. 文档中可以使用的标签  
  118. <b>  
  119. <code>  
  120. <br>  
  121. <kdb>  
  122. <li>  
  123. <pre>  
  124. <ul>  
  125. <samp>  
  126. <var>  

 

 

附录三：

一段含有规范注释的php代码 :

[php] view plaincopy
  1. 以下为引用的内容：  
  2.   
  3. <?php  
  4. /** 
  5. * Sample File 2, phpDocumentor Quickstart 
  6. * 
  7. * This file demonstrates the rich information that can be included in 
  8. * in-code documentation through DocBlocks and tags. 
  9. * @author Greg Beaver <cellog@php.net> 
  10. * @version 1.0 
  11. * @package sample 
  12. */  
  13. // sample file #1  
  14. /** 
  15. * Dummy include value, to demonstrate the parsing power of phpDocumentor 
  16. */  
  17. include_once 'sample3.php';  
  18. /** 
  19. * Special global variable declaration DocBlock 
  20. * @global integer $GLOBALS['_myvar'] 
  21. * @name $_myvar 
  22. */  
  23. $GLOBALS['_myvar'] = 6;  
  24. /** 
  25. * Constants 
  26. */  
  27. /** 
  28. * first constant 
  29. */  
  30. define('testing', 6);  
  31. /** 
  32. * second constant 
  33. */  
  34. define('anotherconstant', strlen('hello'));  
  35. /** 
  36. * A sample function docblock 
  37. * @global string document the fact that this function uses $_myvar 
  38. * @staticvar integer $staticvar this is actually what is returned 
  39. * @param string $param1 name to declare 
  40. * @param string $param2 value of the name 
  41. * @return integer 
  42. */  
  43. function firstFunc($param1, $param2 = 'optional') {  
  44. static $staticvar = 7;  
  45. global $_myvar;  
  46. return $staticvar;  
  47. }  
  48. /** 
  49. * The first example class, this is in the same package as the 
  50. * procedural stuff in the start of the file 
  51. * @package sample 
  52. * @subpackage classes 
  53. */  
  54. class myclass {  
  55. /** 
  56. * A sample private variable, this can be hidden with the --parseprivate 
  57. * option 
  58. * @accessprivate 
  59. * @var integer|string 
  60. */  
  61. var $firstvar = 6;  
  62. /** 
  63. * @link http://www.example.com Example link 
  64. * @see myclass() 
  65. * @uses testing, anotherconstant 
  66. * @var array 
  67. */  
  68. var $secondvar =  
  69. array(  
  70.     'stuff' =>  
  71.                  array(  
  72.                                   6,  
  73.                                   17,  
  74.                                   'armadillo'  
  75.                           ),  
  76.     testing => anotherconstant  
  77. );  
  78. /** 
  79. * Constructor sets up {@link $firstvar} 
  80. */  
  81. function myclass() {  
  82. $this->firstvar = 7;  
  83. }  
  84. /** 
  85. * Return a thingie based on $paramie 
  86. * @param boolean $paramie 
  87. * @return integer|babyclass 
  88. */  
  89. function parentfunc($paramie) {  
  90. if ($paramie) {  
  91. return 6;  
  92. } else {  
  93. return new babyclass;  
  94. }  
  95. }  
  96. }  
  97. /** 
  98. * @package sample1 
  99. */  
  100. class babyclass extends myclass {  
  101. /** 
  102. * The answer to Life, the Universe and Everything 
  103. * @var integer 
  104. */  
  105. var $secondvar = 42;  
  106. /** 
  107. * Configuration values 
  108. * @var array 
  109. */  
  110. var $thirdvar;  
  111. /** 
  112. * Calls parent constructor, then increments {@link $firstvar} 
  113. */  
  114. function babyclass() {  
  115. parent::myclass();  
  116. $this->firstvar++;  
  117. }  
  118. /** 
  119. * This always returns a myclass 
  120. * @param ignored $paramie 
  121. * @return myclass 
  122. */  
  123. function parentfunc($paramie) {  
  124. return new myclass;  
  125. }  
  126. }  
  127. ?>