问题标签 [docblocks]

For questions regarding programming in ECMAScript (JavaScript/JS) and its various dialects/implementations (excluding ActionScript). Note JavaScript is NOT the same as Java! Please include all relevant tags on your question; e.g., [node.js], [jquery], [json], [reactjs], [angular], [ember.js], [vue.js], [typescript], [svelte], etc.

0 投票
2 回答
2966 浏览

php - 如何将 docblock 提示与 $this 变量的类一起使用?

我使用 NetBeans 作为我的 IDE。每当我有一些代码使用另一个函数(通常是工厂)来返回一个对象时,通常我可以执行以下操作来帮助提示:

但是,当我使用对象的属性来存储该类时,我有点茫然如何做同样的事情,因为trying to use @var $this->foo or @var foo不会通过提示:

我已经在类的文档块中尝试过,或者使用上面的内联注释protected $foo或将 foo 设置为实例的位置。

到目前为止,我发现的唯一解决方法是:

不过,我真的希望提示是类范围的,因为许多其他函数可能会使用$this->foo,并且知道类的方法和属性会很有用。

当然还有更直接的方法...

0 投票
1 回答
1338 浏览

git - PHPDocblocks 和 Git 的自动版本号

我在 Netbeans 中编写代码并使用 Git 作为我的版本控制系统。

我已经看到,如果我要使用 SVN,我可以添加$Id$到我的 docblocks,以便为每个提交的更改自动插入一个版本,例如:

有没有办法用 Git 做到这一点?

你们如何管理文档中的版本号?手动更新真的很痛苦,而且不太实用。

0 投票
1 回答
408 浏览

php - 在 PHP 文档块中包含 @param varname 是否仍然合适?

根据维基百科@param,文档块参数type [$varname] description的格式$varname是可选的。这似乎得到了 phpDocumentor 项目的支持,该项目指出

注意:从 0.4.1 开始,@param 可以记录 phpdoc.de 样式,带有可选的 $paramname

那么包含 $paramname 是否仍然是正确的形式,还是应该省略?

0 投票
1 回答
247 浏览

php - PHP 动态页面级 DocBlocks

我想知道是否有办法与页面级 DocBlocks 交互。我的问题更具体地说是关于 wordpress 插件开发,但这个问题也出现在非 wordpress 环境中。

原因主要是可以在整个大型项目中轻松更改版本和名称,并且可能具有恒定的定义 - 但这也将反映在 docblock..

以下示例 Docblock 来自我编写的 wordpress 插件 -

有没有办法将其转换为:

显然,要使 echo 工作,我需要破坏 docblock 本身,并且我不能将 docblock 直接写入它自己的文件中。

简而言之:我能否以某种方式用 php 本身“生成”一个 docblock(我认为答案是 - 页面本身的“否”.. 但也许我错了,有人有一些巧妙的 hack :-))

这甚至可能吗?

0 投票
1 回答
924 浏览

php - 像@static这样的冗余php docblock标签有什么意义?

在 PhpStorm 中使用自动 php docblock 生成时,我最终得到@static了静态方法上的注释:

如果可以从代码中推断出这些标签,它们有什么用处吗?我正在尝试决定是否应该保留它或删除它(并且在任何地方都这样做,以便保持一致)。

0 投票
2 回答
2068 浏览

php - DocBlock 类类型继承

虽然这个问题一般是关于DocBlocks的,但我的用例是关于 PHP 的。

考虑以下 PHP 代码:

这只是一个带有一些链接的微不足道的类。扩展类失去了类型提示,因为父类的 docblock 正在使用一个特定的类名,该类名没有子类的方法/属性。

假设我们确实需要类型提示功能,(如果没有,请留下这个问题 - 我不想要无用的参数),我应该如何解决这个问题?

我想出了以下几种可能性:

  • 更改 PHPDoc 标准以允许使用特殊关键字
  • 添加一个多余的 say_hi() 方法,它调用父级只是为了重新声明 docblock
  • 根本不指定返回类型,让 IDE 决定什么return $this;意思(这甚至可以工作吗?)
0 投票
1 回答
435 浏览

php - PHP "namespaced" docblock tags?

I've seen this used (example from Doctrine2) in a lot of libraries that have code which works with comments:

I seems as though some of the comment tags are "namespaced". Is this some PHP feature that I'm not aware of (since it seems to work with the "use" statements), or is it just some smart text parsing within the library that uses these?

I am asking because I am currently developing a small class that has to read some of this "metadata", and it would be really neat if this is something that is included in the language, so I don't have to write ugly text parsers.

Many thanks in advance.

0 投票
2 回答
6854 浏览

php - 什么时候应该在 PHPDoc 类型提示和文档块中使用 NULL?

null在使用PHPDoc 描述变量时,我对何时使用 as 类型感到困惑。类型提示是否应该描述外部调用者预期和遵守的希望和期望,或者它们是否应该记录变量的所有可能类型,即使希望它在实践中是一种非常具体的类型?

示例 1:默认值。以下函数只需要非空值。但是,如果没有传递任何值,它默认null并显式检查该值,以确定是否传递了任何值,并为这种情况返回一个特殊值。希望没有外部调用者会传递除整数之外的任何内容。应该null@param下面的类型中使用,还是应该只指定int,因为这是我们想要传递的,如果有任何传递?

示例 2:实例属性。我们只希望 $bar 包含整数。也就是说,如果没有为 bar 设置任何内容,则此实例属性的默认 PHP 值为 null。我是否需要在每个使用 $bar 的地方都考虑到这一点,可能的 null 类型如下?

基本上,我发现自己几乎在每一个@param@var声明中都乱扔垃圾,|null因为从技术上讲,它可能就是那个价值。但在实践中不应该如此。我是否应该期望我的几乎所有类型都包含null或应该假设的可能性,并且我应该避免指定它,除非我希望null明确设置或接收一个值?

0 投票
1 回答
951 浏览

php - Magento模板中当前对象的PHP Docblock类型提示?

我如何$this使用 DocBlock 暗示 Magento 模板的上下文中的内容?

例如,head.phtml目录template/page/html/中有一个Mage_Page_Block_Html_Head. 我尝试的方法是:

不幸的是,我的 IDE ( NetBeans )似乎没有收到提示。所以我的问题是,是否有正确的方法可以让 NetBeans 识别提示。

0 投票
1 回答
452 浏览

php - Php Docblocks @version $Id$ 不适用于 NetBeans SVN 插件

对于我正在进行的项目,我们使用 SVN。所以我为 Netbeans 安装了 SVN 插件,到目前为止效果很好。

现在在类和其他 php 文件中,我们使用带有 @version 标签的 docblocks。我想知道如何让插件自动填充/替换版本标签中的 $Id$?

我目前正在使用 Win7 和 NetBeans 7.1.2。我在下面的配置文件中添加了以下几行%APPDATA%\Roaming\Subversion config

我还从以下行中删除了评论:

重新启动 NetBeans 后,我注意到 (UserPath).netbeans\7.1.2\config\svn\config 中的配置文件已使用先前添加的数据进行了更新。

但是,如果我提交更改的文件,@version 标记不会更新。之后只剩下 $Id$。我做错了什么或者我错过了配置什么?

它应该如下所示: