·您当前的位置:主页 > 技术教程 > PHP教程 >

[php]PHP注释的标准文档写得非常好的文档范例(翻译自Wiki)PHPD

时间:2016-12-30 10:38酷播
[php]PHP注释的标准文档写得非常好的文档范例(翻译自Wiki)PHPDoc

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

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

原文截图:

PHPDoc注释实例:

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

 

热门文章

请稍候...
  • 热身双十一,锁定云视频大聚惠
  • 备战双十一,相约直播超值狂欢
保利威视云直播
保利威视云视频
微信付费直播
酷播云免费在线视频整体解决方案
酷播v4.0网页播放器