前言
维基百科：PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor 这样的外部文档生成器生成 API 文档，也可以帮助一些例如 Zend Studio, NetBeans, ActiveState Komodo Edit and IDE 和 Aptana Studio 之类的 集成开发环境 理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成，类型提示和除错功能。 PHPDoc 可同时支持 面向对象 的和 面向过程的 代码。
PHPDoc注释标签
注：目前这个文档还属于Draft(拟稿)状态，仅供参考。
5.1. @api
表示这是一个提供给第三方使用的 API 接口
语法
@api
Examples
class UserService
{
/**
* This method is public-API.
*
* @api
*/
public function getUser()
{
}
/**
* This method is "package scope", not public-API
*/
public function callMefromAnotherClass()
{
}
}
5.2. @author
作者
语法
@author [name] []
Examples
/**
* @author My Name
* @author My Name
*/
5.3. @copyright
版权声明
语法
@copyright
Examples
/**
* @copyright 1997-2005 The PHP Group
*/
5.4. @deprecated
不建议使用的、已过期的、将被删除的
语法
@deprecated [] []
Examples
/**
* @deprecated
*
* @deprecated 1.0.0
*
* @deprecated No longer used by internal code and not recommended.
*
* @deprecated 1.0.0 No longer used by internal code and not recommended.
*/
5.5. @internal
仅限内部使用的
语法
@internal [description]
or inline:
{@internal [description]}
Contrary to other inline tags, the inline version of this tag may also contain other inline tags (see second example below).
Examples
Mark the count function as being internal to this project:
/**
* @internal
*
* @return int Indicates the number of items.
*/
function count()
{
}
Include a note in the Description that only Developer Docs would show.
/**
* Counts the number of Foo.
*
* This method gets a count of the Foo.
* {@internal Developers should note that it silently
* adds one extra Foo (see {@link http://example.com}).}
*
* @return int Indicates the number of items.
*/
function count()
{
}
5.6. @link
链接，可用于辅助说明、引用文档等
语法
@link [URI] [description]
or inline
{@link [URI] [description]}
Examples
/**
* @link http://example.com/my/bar Documentation of Foo.
*
* @return int Indicates the number of items.
*/
function count()
{
}
/**
* This method counts the occurrences of Foo.
*
* When no more Foo ({@link http://example.com/my/bar}) are given this
* function will add one as there must always be one Foo.
*
* @return int Indicates the number of items.
*/
function count()
{
}
5.7. @method
方法。这是用在类注释里的标记。特别适合一些动态加载的类，IDE 无法自动提示出来，这时就可以通过写 @method 标记来告诉 IDE 我这类里有哪些方法
语法
@method [return type] [name]([type] [parameter], [...]) [description]
@method tags can ONLY be used in a PHPDoc that is associated with a class or interface.
Examples
class Parent
{
public function __call()
{
}
}
/**
* @method setInteger(int $integer)
* @method string getString()
* @method void setString(int $integer)
*/
class Child extends Parent
{
}
5.8. @package
包。但 php没有包，所以就用来表示命名空间
语法
@package [level 1]\[level 2]\[etc.]
该标签不得在“ DocBlock”中多次出现。
Examples
/**
* @package PSR\Documentation\API
*/
5.9. @param
参数，用于函数和方法注释里的标记
语法
@param ["Type"] [name] []
Examples
/**
* Counts the number of items in the provided array.
*
* @param mixed[] $items Array structure to count the elements of.
*
* @return int Returns the number of elements.
*/
function count(array $items)
{
}
5.10. @property
类属性，与 @method 类似，可以告诉 IDE 我这类里有哪些属性
语法
@property[] ["Type"] [name] []
The @property tags can ONLY be used in a PHPDoc that is associated with a class or trait.
Example
In the following example, a class User implements the magic __get() method, in order to implement a "magic", read-only $full_name property:
/**
* @property-read string $full_name
*/
class User
{
/**
* @var string
*/
public $first_name;
/**
* @var string
*/
public $last_name;
public function __get($name)
{
if ($name === "full_name") {
return "{$this->first_name} {$this->last_name}";
}
}
}
5.11. @return
返回值
语法
@return [description]
Examples
/**
* @return int Indicates the number of items.
*/
function count()
{
}
/**
* @return string|null The label's text or null if none provided.
*/
function getLabel()
{
}
5.12. @see
参考，类似 @link，可与 @deprecated 联动
语法
@see [URI | "FQSEN"] []
Examples
/**
* @see number_of() :alias:
* @see MyClass::$items For the property whose items are counted.
* @see MyClass::setItems() To set the items for this collection.
* @see http://example.com/my/bar Documentation of Foo.
*
* @return int Indicates the number of items.
*/
function count()
{
}
5.13. @since
从 xx 版本开始。例如从 1.0 之后添加了 xx 功能、删除了 xx 参数等
语法
@since [] []
Examples
/**
* This is Foo
* @version 2.1.7 MyApp
* @since 2.0.0 introduced
*/
class Foo
{
/**
* Make a bar.
*
* @since 2.1.5 bar($arg1 = '', $arg2 = null)
* introduced the optional $arg2
* @since 2.1.0 bar($arg1 = '')
* introduced the optional $arg1
* @since 2.0.0 bar()
* introduced new method bar()
*/
public function bar($arg1 = '', $arg2 = null)
{
}
}
5.14. @throws
可能会抛出的错误类型
语法
@throws ["Type"] []
Examples
/**
* Counts the number of items in the provided array.
*
* @param mixed[] $array Array structure to count the elements of.
*
* @throws InvalidArgumentException if the provided argument is not of type
* 'array'.
*
* @return int Returns the number of elements.
*/
function count($items)
{
}
5.15. @todo
待办。提示自己或他人还需要做些什么
语法
@todo [description]
Examples
/**
* Counts the number of items in the provided array.
*
* @todo add an array parameter to count
*
* @return int Returns the number of elements.
*/
function count()
{
}
5.16. @uses
使用
语法
@uses [file | "FQSEN"] []
Examples
/**
* @uses \SimpleXMLElement::__construct()
*/
function initializeXml()
{
}
/**
* @uses MyView.php
*/
function executeMyView()
{
}
5.17. @var
变量
语法
@var ["Type"] [element_name] []
Examples
/** @var int $int This is a counter. */
$int = 0;
// there should be no docblock here
$int++;
Or:
class Foo
{
/** @var string|null Should contain a description */
protected $description = null;
public function setDescription($description)
{
// there should be no docblock here
$this->description = $description;
}
}
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
/** @var \Sqlite3 $sqlite */
foreach ($connections as $sqlite) {
// there should be no docblock here
$sqlite->open('/my/database/path');
}
Even compound statements may be documented:
class Foo
{
protected
/**
* @var string Should contain a description
*/
$name,
/**
* @var string Should contain a description
*/
$description;
}
Or constants:
class Foo
{
const
/**
* @var string Should contain a description
*/
MY_CONST1 = "1",
/**
* @var string Should contain a description
*/
MY_CONST2 = "2";
}
5.18. @version
版本号
语法
@version ["Semantic Version"] []
Examples
/**
* File for class Foo
* @version 2.1.7 MyApp
* (this string denotes the application's overall version number)
* @version @package_version@
* (this PEAR replacement keyword expands upon package installation)
* @version $Id$
* (this CVS keyword expands to show the CVS file revision number)
*/
/**
* This is Foo
*/
class Foo
{
}
问题思考
关于类、方法或函数的创建时间，没有明确的标签来显示。目前个人习惯用@date，但@date并不存在于官方标签，没有IDE提示。
/**
* @version v3 2020-10-09
* @date 2020-10-09
*/
class TestController
{
// TODO 表示还没做的事，就是还没写的代码。
// FIXME 表示可能有些功能已经实现了但不是最好的，或者存在异常隐患，需要后面更改的
}
不知道各位同学是如何处理的，欢迎留言讨论。
补充
关于@example等，请参考phpdoc。
参考链接
本文会持续修正及补充，欢迎大家留言纠错。
1254
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
