• 【转】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();
         }
     }
     ?>
  • 相关阅读:
    Redis
    Ajax和JSON
    快速幂
    欧拉函数
    约数
    质数
    二分图相关算法模板
    最小生成树模板
    最短路算法模板
    康托展开和逆康托展开
  • 原文地址:https://www.cnblogs.com/fzzl/p/2807888.html
Copyright © 2020-2023  润新知