问题标签 [docblocks]

我喜欢用于崇高文本的插件DocBlockr，但我希望我的评论有点不同。

正常外观：

以及我希望它们如何出现：

那么type,description没有[]方括号是否有这样做的呢？我用谷歌搜索并查看了文档，但找不到。下面的图片直接取自文档页面。

我希望有人可以帮助我，因为发表评论会变得容易得多。

我有一个处理错误的类，它没有使用该try-throw-catch机制。

当我评论使用该类的代码时，@throws即使我实际上没有抛出任何东西，我是否应该使用该标签？

编辑（尽量让我的问题更清楚）：

我的问题是@throws标签是否意味着在使用代码时可能发生错误并且我正在以某种方式处理它，或者这意味着可能发生错误并且我正在通过throw专门使用关键字来处理它？

假设我有一行summary，我必须像这样纠正它：

或者我可以这样写：

我更喜欢第二个选项，但是使用第一个选项是否需要？

我有这个功能：

我想创建一个描述它的 DocBlock。仅当所需的控制器有效时，此函数才返回控制器对象，否则，它会创建ErrorController类的实例，但不返回值。我怎样才能为这个功能正确的@return标签？

我特别着迷于这种非代码代码的当前用法（如非代码，它不是文件其余部分的语言），以及这种非代码代码的历史。

在某些情况下，这可以称为元编程，但我认为这并不涵盖所有情况。

我已经看到它用于很多事情，可以追溯到 80 年代（根据我的经验），在 C 注释中使用“Autodocs”，用于生成文档，一直到 PHP 等解释语言中非常复杂的现代化身您在注释块中有注释，它们用于文档，在 PHP 语法不足的地方添加额外的含义，以及其他类型的“元”数据。

它似乎是一个大杂烩。我还不确定我对此有何感想。似乎有些不对劲。但我看到它有很大的用处。

我想知道您将使用什么通用术语来涵盖几乎所有代码中的所有这些非代码代码案例，以及是否有任何关于该主题及其历史、最佳实践等的权威著作。如果没有，它让我感兴趣，因为我想自己研究和写作。

例如，在 PHP 领域，我们有这样的事情：

无论如何，我看到有很多工具使用这些东西，但有很多重叠和碎片化。至少在 PHP 领域。我回想起多年来的编程，我认为这类东西并不是什么新鲜事。

我想搜索该主题，但找不到一个好的搜索词来获得我正在寻找的内容，这是有关此类方法起源的一些历史文档，多年来哪些工作做得好或不好，最佳实践等。这都被认为是元编程吗？

这些东西的演变是什么，它们是在某个时候成为语言的适当部分，还是融入到新的语言中？

我对这个主题很感兴趣，我想知道是否有其他人写过关于这个主题的权威文本？

我突然想到，这些东西实际上是领域特定语言的一种形式。因为宿主语言无法表达某些东西，所以使用 DSL 并将其嵌入到代码中（在注释中或通过宿主语言支持的某些工具，如注释）来表达您希望与代码，而不必对代码流产生任何影响。

如何使用@param来提示作为属性 ( )的可选参数以及用于提示其返回类型？functionthis.selectedPage()@type

以这个为例（this.selectedPage()可以通过传递参数接收页面并通过传递无返回）：

type-typehint 很好地被 IDE 接收，并允许自动完成this.selectedPage()产生Page.

但是，还请注意，它this.selectedPage()需要一个参数——即一个页面。否则 IDE 会抱怨该函数在尝试传递 1 时允许 0 参数。

所以我将两者结合起来：

这似乎阻止了 IDE 在尝试传递参数时抱怨，但现在它在不传递参数时抱怨。

我试过@type {function(undefined|Page): Page}无济于事。

该函数是一个 getter/setter - 那么如何告诉 docblock @param 是可选的呢？

当我编写代码时，让我（或其他人）清楚地了解正在发生的事情对我来说非常重要，这样我（或其他人）就不需要在以后浪费时间试图重新弄清楚所有事情。因此，我首先寻求有关回调命名约定的最佳实践。

此外，最近从 PHP (Symfony2) 切换并在我的 IDE 中使用 DocBlock 进行提示，我试图找出一种类似的方法来在我的 Javascript 代码中获得有用的提示。

例如：

如果有人可以回答这些问题或将我链接到一些带有建议的好文档，那么我将非常感激。到目前为止，我发现这个很有帮助：

http://callbackhell.com/

但是，诸如此类的搜索查询docblock callbacks并没有提供任何有用的信息。

我刚刚写了一个这样的函数

但是在制作 docblock 时，我意识到这@return \React\Promise\ExtendedPromiseInterface是非常通用的，并不能真正帮助客户了解在拒绝或履行的情况下预期的回报。

是否有一些既定的约定来记录该函数的预期值或异常，以便客户端可以通过仅查看接口来链接该函数？

我们已经有了相反的约定，在 phpUnit 测试文档块中使用@covers注释是正常的。

如果您正在查看一段代码，那么查看执行该逻辑的测试通常会有所帮助，以了解代码应该做什么。在 PHP 中，是否有约定在您的代码中记录在哪里可以找到为执行该功能而编写的测试？如果没有，我们计划采用我们自己的约定并正在考虑以下选项之一：

• 使用phpDocumentor@internal注释
• 使用完全自定义的注释，例如@spec
• 只是 docblock 中的一个免费评论，但样式以快速可识别的模式
• 不要记录，而是通过注释代码找出测试的位置，运行测试套件并查看哪些测试失败。

是否有任何警告不要使用这些？

我在 ZF1 的评论/文档中发现了一些特殊符号“#@+”和“#@-”。例子：

（https://github.com/zendframework/zf1/blob/master/library/Zend/Mail.php#L54）

我以前在另一个不同的存储库中看到过。

这些是什么意思？