为常量编写 PHPDocs 的正确方法是什么？

发布于 2024-11-24 01:44:57 字数 206 浏览 2 评论 0原文

我有这样的代码：

/**
 * Days to parse
 * @var int
 */
const DAYS_TO_PARSE = 10;
...

我不认为使用 @var 对于常量是正确的，并且我没有看到任何 @constant PHPDoc 标记。这样做的正确方法是什么？

原文

I have this code:

/**
 * Days to parse
 * @var int
 */
const DAYS_TO_PARSE = 10;
...

I don't think that using @var is correct for a constant and I don't see any @constant PHPDoc tag. What is the correct way to do this?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

遮云壑 2024-12-01 01:44:58

PHP-FIG 建议使用 @var 作为常量。

7.22。 @var
您可以使用@var标签来记录以下的“类型”
“结构要素”：
常量，包括类范围和全局范围
属性
全局和局部范围的变量
语法
@var [“类型”] [元素名称] [<描述>]

回复收藏 0 原文

鹿童谣 2024-12-01 01:44:58

@const 是不是正确的答案。

它不是旧版 phpDocumentor 文档的一部分： http://manual.phpdoc.org/HTMLframesConverter/default/< /a>
它不是当前 phpDocumentor 文档的一部分： http://www.phpdoc.org/docs/latest/index.html
它没有列在维基百科的标签列表中：http://en.wikipedia.org/wiki/PHPDoc#Tags
它未在 PHP-FIG 草案 PSR 中列出：https://github.com/phpDocumentor/fig-standards /blob/master/propose/phpdoc.md#7-tags

列出的唯一“官方”位置是 phpdoc.de，但那里的规范仅适用于1.0beta，并且该网站还包含像 @brother 和 @sister 这样的标签，我以前从未见过使用过这些标签，因此对该网站的整体信任度有所下降； -) 事实上的
标准一直是 phpDoc.org。

简而言之，即使某些非官方标准确实提到了它，如果文档生成器不支持它，那么它就不值得使用。

@var 目前是正确的 ~~，一旦 PSR（上面列表中的最后一个链接）不再草稿，并且是 phpDocumentor、Doxygen、APIGen 和其他人理解 PHPDoc 的基础，那么 @type 是正确的，它是 @var~~ 的后继者。

回复收藏 0 原文

能否归途做我良人 2024-12-01 01:44:58

不需要注释常量的类型，因为类型始终是：

标量或数组
在声明时已知的
不可变的

@const 也不是 PHPDoc 标准的一部分。 PHP-FIG 建议使用 @var 但这不受 PHPDoc 支持，并且不会添加任何您无法从声明本身推断出的信息。

因此，为了可读性，我建议只使用一个普通的 PHPDoc 文档块来记录您的常量：

class Foo
{
    /**
     * This is a constant.
     */
    const BAR = 'bar';
}

它将在您生成 PHPDocs 时描述常量，同时保持注释的干净和可读。

There is no need to annotate the type of constants, since the type is always:

either a scalar or an array
known at declaration time
immutable

@const is also not part of the PHPDoc standard. PHP-FIG suggests @var but this is not backed by PHPDoc and doesn't add any information you can't already deduce from the declaration itself.

Therefore, for the sake of readability I recommend just using a plain PHPDoc docblock to document your constants:

class Foo
{
    /**
     * This is a constant.
     */
    const BAR = 'bar';
}

It will describe the constant when you generate PHPDocs yet keeps the comments clean and readable.

回复收藏 0 原文

舞袖。长 2024-12-01 01:44:58

我使用 Netbeans。当使用这种格式时，它将解析 phpDoc 的全局常量和类常量：

/** @const Global constant description */
define('MY_CONST', 10);

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}

I use Netbeans. It will parse phpDoc for global and class constants when this format is used:

/** @const Global constant description */
define('MY_CONST', 10);

class MyClass
{
    /** @const Class constant description */
    const MY_CONST = 10;
}

回复收藏 0 原文

尛丟丟 2024-12-01 01:44:58

以下提案尊重官方文档语法：

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}

The following proposition respects the official documentation syntax:

class Foo
{
    const
        /**
         * @var string Should contain a description
         */
        MY_CONST1 = "1",
        /**
         * @var string Should contain a description
         */
        MY_CONST2 = "2";

}

回复收藏 0 原文