【转】PHP经验——PHPDoc PHP注释的标准文档(翻译自Wiki)

转自:PHP经验——PHPDoc PHP注释的标准文档(翻译自Wiki)

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

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

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

相关参考资料:

http://manual.phpdoc.org/HTMLSmartyConverter/PHP/li_phpDocumentor.html

http://www.ibm.com/developerworks/cn/linux/sdk/php/pear3/index.html

http://www.phpdoc.org/docs/latest/index.html

http://blog.csdn.net/eric6/article/details/5888894

 

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   文档、类、函数的版本信息

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

英文说明:

Common tags
TagUsageDescription
@abstract   Documents an abstract class, class variable or method.
@access public, private or protected Documents access control for an element. @access private indicates that documentation of element be prevented.
@author author name <author@email> Documents the author of the current element.
@copyright name date Documents copyright information.
@deprecated version Documents a method as deprecated.
@deprec   Same as @deprecated
@example /path/to/example Documents the location of an external saved example file.
@exception   Documents an exception thrown by a method — also see @throws.
@global type $globalvarname Documents a global variable or its use in a function or method.
@ignore   Prevents the documentation of an element
@internal   Private information for advanced developers
@link URL  
@name global variable name Specifies an alias for a variable. For example, $GLOBALS['myvariable'] becomes $myvariable
@magic   phpdoc.de compatibility "phpDocumentor tags".
@package name of a package Documents a group of related classes and functions.
@param type [$varname] description  
@return type description This tag should not be used for constructors or methods defined with a void return type.[citation needed]
@see element Documents an association to any element (global variable, include, page, class, function, define, method, variable).
@since version Documents when a method was added to a class.
@static   Documents a static class or method
@staticvar type Documents a static variable's use in a function or class
@subpackage    
@throws   Documents an exception thrown by a method.
@todo   Documents things that need to be done to the code at a later date.
@var type A data type for a class variable
@version   Provides the version number of a class or method.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

PHPDoc注释示例:

<?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();
     }
 }
 ?>

 

 

 

 

 

posted on 2012-12-07 21:03  风在竹林  阅读(450)  评论(0编辑  收藏  举报