<?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 声明也具有相同效果（沒有返回任何值）。
PHPDocument 标签原文地址。
| 标签 | 适用 | 描述 |
|---|---|---|
| api | 方法 | 声明此元素适用于第三方 |
| author | 任何 | 记录相关作者 |
| category | 文件,类 | 分类 |
| copyright | 任何 | 记录相关版权信息 |
| deprecated | 任何 | 声明此元素不推荐使用, 以后将会弃用 |
| example | 任何 | 显示一部分示例代码 |
| filesource | 文件 | 当前文件的包含源文件 |
| global | 变量 | 告知phpDocumentor全局变量及其用法 |
| ignore | 任何 | 告知phpDocumentor忽略的元素 |
| internal | 任何 | 说明此元素是相关程序或库的内部元素，默认隐藏 |
| license | 文件, 类 | （开源）许可证 |
| link | 任何 | 相关链接 |
| method | 类 | 声明可调用的魔术方法 |
| package | 文件, 类 | 所属包 |
| param | 方法, 函数 | 声明程序或方法所用到的参数 |
| property | 类 | 声明类存在的魔术属性 |
| property-read | 类 | 声明类存在的只读魔术属性 |
| property-write | 类 | 声明当前类所有的只写魔术属性 |
| return | 方法, 函数 | 声明当前方法或函数的返回类型 |
| see | 任何 | 相关参考 |
| since | 任何 | 声明可用版本 |
| source | 任何(除了文件) | 参考来源（源代码） |
| subpackage | 文件, 类 | 所属子包 |
| throws | 方法, 函数 | 声明异常类型 |
| todo | 任何 | 计划还要做的开发任务 |
| uses | 任何 | 表示对（和）单个关联元素的引用。 |
| var | 属性 | xxx |
| version | 任何 | 版本 |