PHPDoc - [ PHP编程之道 ] - 在线原生手册

目录搜索

前言入门指南代码风格指南语言亮点编程范式命名空间 PHP标准库命令行接口 Xdebug 依赖管理使用当前稳定版本的 PHP (7.1) Mac 系统安裝 PHP Windows 系统安裝 PHP 内置的 web 服务器 Composer 与 Packagist PEAR 介绍开发实践基础知识日期和时间设计模式使用 UTF-8 编码国际化 (i18n) 与本地化 (l10n) 一般的实现方法 Gettext 依赖注入基本概念复杂的问题容器数据库 MySQL 扩展 PDO 扩展数据库交互数据库抽象层使用模板好处原生 PHP 模板编译型模板错误与异常错误异常安全 Web 应用程序安全密码哈希数据过滤配置文件注册全局变量错误报告测试测试驱动开发其他测试工具服务器与部署虚拟或专用服务器共享主机构建及部署应用虚拟化技术 Vagrant 简介 Docker 简介缓存 Opcode 缓存对象缓存文档撰写 PHPDoc 资源 PHP 官方值得关注的大牛指导 PHP 的 Paas 提供商框架组件其他有用的资源书籍社区 PHP 用户组 PHP 会议 ElePHPants

文字

PHPDoc 是注释 PHP 代码的非正式标准。它有许多不同的标记可以使用。完整的标记列表和范例可以查看 PHPDoc 指南。

如下是撰写类方法时的一种写法：

<?php 
/**  
* @author A Name <a.name@example.com>  
* @link http://www.phpdoc.org/docs/latest/index.html  
*/ 
class DateTimeHelper {     
    /**      
    * @param mixed $anything Anything that we can convert to a \DateTime object      
    *      
    * @throws \InvalidArgumentException      
    *      
    * @return \DateTime      
    */     
    public function dateTimeFromAnything($anything){         
        $type = gettype($anything);         
        switch ($type) {            
         // Some code that tries to return a \DateTime object         
         }         
         throw new \InvalidArgumentException(             
             "Failed Converting param of type '{$type}' to DateTime object"         );     
             }     
             /**      
             * @param mixed $date Anything that we can convert to a \DateTime object      
             *      
             * @return void      
             */     
             public function printISO8601Date($date){         
                 echo $this->dateTimeFromAnything($date)->format('c');     
                 }     
                 /**      
                 * @param mixed $date Anything that we can convert to a \DateTime object      
                 */     
                 public function printRFC2822Date($date){         
                     echo $this->dateTimeFromAnything($date)->format('r');     
                 } 
}

这个类使用了 @author 和 @link 标记来为整个类添加说明。 @author 标记是用來说明代码的作者，在多位开发者的情况下，可以同时列出好几位作者。其次 @link 标记用来提供网站链接，进一步说明代码和网站之间的关系。

在这个类中，第一个方法的 @param 标记，说明类型、名字和传入方法的参数。此外，@return 和 @throws 标记分别说明返回类型以及可能抛出的异常。

第二和第三个方法非常类似，和第一个方法一样使用了一个 @param 标记。第二、和第三个方法之间关键差別在注释区块使用／排除 @return 标记。@return void 标记明确告诉我们没有返回值，而过去省略 @return void 声明也具有相同效果（沒有返回任何值）。