问题标签 [docblocks]

我是来自 PHP 的 Python 新手，我知道 Python 有 Docstrings，但是如何在类变量上做到这一点？假设在 PHP 中我有：

现在我将如何实现这是python？就像是：

我的项目使用 WordPress 入门主题 FoundationPress。upstream remote我使用 Github 并在社区改进代码时从父存储库更新我的项目。作为记录，我已经编程了很长时间，但几乎总是一个人，而且我对 docblocks 和代码内文档非常缺乏经验。我知道在某种程度上这可能是基于意见的，因为这似乎是寻找其他答案的趋势，但我觉得我没有掌握正确的用法。

父项目在 PHP 文件上使用如下所示的 PHP Docblocks，每个文件始终只有一次，例如：

当我添加自己的新 PHP 文件时，我一直在添加一个类似的块，但使用我的项目的名称代替：

有时，我会使用自己的函数更新现有文件。我一直把@since这些功能放在上面，所以它是这样的：

其他时候，我更新了一个现有的函数——我只是把 docblock 留给那些，但我想知道我是否应该更新任何东西。

1. 是否有最佳实践或至少普遍接受的方式来处理这种情况（一个与父存储库保持同步的分叉项目），以便我的代码对其他程序员更有用？
2. 似乎还有很多其他 docblock 参数和选项，例如每个函数的 docblocks。我应该争取推荐的详细程度吗？
3. 是否有在我的项目中在其他类型的文件（SCSS、JS 等）上添加类似文档的最佳实践？父项目似乎没有，但我有兴趣添加一些。

我的目标是以同事或未来的维护者将来可能会发现有用的格式创建代码和代码内文档。

我正在构建一个使用 Doctrine Annotations 库实现自定义 docblock 注释的应用程序。

对于 PHPUnit 测试，是否可以创建一个具有模拟文档块的模拟类？

从这个答案中，我学会了如何模拟一个类，如下所示：

有没有办法模拟一个文档块？在类示例的基础上，我想象的是这样的事情：

如果没有 - 除了创建实际的测试类之外我还能做些什么吗？

正在生成所有其他文件的文档，但对于 src/Pagination/Paginator.php，它不是。这是一个 Symfony 4 应用程序。

相关的错误是：

没有总结？那是错误的。该文件在结构上似乎与其他文件没有什么不同。文件的 DocBlock 和每个类的 DocBlock。看一看：

当浏览生成的文档时，Paginator 类就不见了。走了。这里发生了什么？

我在 Windows 系统上使用 PHAR 文件。它位于项目的根目录，就在 src/ 之外。GraphViz 是后来手动安装的。

这是我使用的命令：

这是输出：

目前在我的 PhpStorm 上，我启用了以下选项：

所以根据这些设置，我的功能应该是这样的：

当我有一个没有 docblock 的函数并且我按下 PhpStorm 为该函数自动生成 docblock 时，它也为已经输入提示的参数生成 docblocks：

所以像这样的函数：

将转换为：

有没有一种方法可以配置我的 PhpStorm只为没有类型提示的参数生成文档块。

请注意，我知道我可以从 PhpStorm 配置模板。我尝试了那个解决方案。

在模板上，您只能告诉 PhpStorm 它是全有或全无。我找不到一种方法来告诉模板只有那些没有类型提示的参数文档块。

我使用 docblocks 来记录函数方法、类……通常。

我发现自己使用了适配器模式，因此，我所有的适配器都实现了一个通用接口并返回相同的东西。

通用接口包含所有函数，并记录了它们的名称、返回值、变量等。

有没有办法让整个适配器类的函数从公共接口中的相同函数继承文档？我知道@inheritDoc但是我不确定是否需要将它用于每个功能，或者是否可以应用于类 docblock，或者这是否完全是一个坏主意。

有点新的“真实”文档。

我有这个代码：

在这种情况下，我在 DocBlock 的示例部分写了一个公平的缩进，但 VSCode 仍然忽略了代码缩进。

当 VSCode 在帮助气泡中显示此文档时，如何强制示例代码中的代码缩进？

TL;博士

如何使用 PhpDoc/DocBlocks 记录在外部代码中定义的常量，以便它不会在静态代码分析中显示为未定义的变量？

细节：

我正在尝试编写一个小型 WordPress 插件。我有一些如下的 PHP 代码。

我正在使用 VSCode 插件vscode-intelephense（它提供 PHP 语言服务）。我安装了所有必要的依赖项，包括在 VSCode 设置中将“wordpress”列为存根。总的来说，intelephense 运行良好，并且在显示有关我的代码以及 WordPress 库代码的信息方面做得很好。

但是 intelephense 显示错误：“未定义的常量 '...\ABSPATH' (1011)”（其中的点是我为简洁起见省略的命名空间）。

所以看起来 intelephense 没有接受第一行暗示的条件——即如果ABSPATH没有定义，执行将不会到达引用它的后面的代码。（这很好，程序流分析可能要求太多）。无论如何，我认为我应该能够添加某种 PhpDoc（或其他注释注释）以向代码分析器表明该变量已定义。像这样的东西：

或这个：

但这些都不会导致错误消失。（我也尝试过@const似乎不是真正的标签。它也不起作用。）

代码中是否有某种方式可以表明 ABSPATH 是在外部代码中定义的，还是在外部范围内定义的？在函数顶部添加一行 likeglobal ABSPATH;似乎也不正确，因为ABSPATH它不是变量。这是一个define-created 常量。

谢谢！

我正在使用代码接收并运行多组示例数据。我正在发送多个接受标头，其中之一是"*/*".

所以示例代码是：

我尝试过双引号内的单引号，我尝试过单引号内的双引号，我尝试过连接每个片段，我尝试过反斜杠，我尝试过 Unicode。PHP 认为 splat 正在与 docblock 对话。我错过了什么？提前致谢！

我有一个内部带有 DocBlock 的 Simulink 模型，我想创建一个脚本来在这个 DocBlock 中编写。我已经有这个代码：

问题是在我运行脚本之后，如果我双击 DocBlock，数据不会改变，我不知道为什么。有人知道如何更改 DocBlock 的内容吗？

编辑：我稍微修改了 set_param 行并添加了一个 get_param 行来验证更改是否正在发生：

当我显示 C 时，它实际上显示了更改，但是当我双击 DocBlock 时它不会更改我真的不明白的数据

谢谢 ！