标签: docblocks

是否可以从现有数据库模式生成带有相关docblock注释的Doctrine 2实体？

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

/**
 * Reset the singleton instance, for the tests only
 * @static
 */
public static function reset() {
    self::$singletonInstance = null;
}

如果可以从代码中推断出这些标签有什么用处吗？我正在试图决定是否应该离开它或将其删除(并且在任何地方都这样做以使其保持一致).

在PhpStorm中,什么是折叠或扩展文件中所有注释(doc)块的快速方法？

在这里的文档中它说:

Folding and expanding code blocks works for entire classes, inner and
anonymous classes, method bodies, import lists, comments, HTML and XML tags,
closures and language injections.

然后进一步说:

If you hold the Alt modifier and click a toggle button in the gutter, the code block
will be collapsed or expanded recursively, i.e. all sub-blocks within the parent 
block will also be collapsed or expanded.

但是我没看到这是如何Alt modifer工作的？我按住Alt然后单击切换按钮,只有该块单独折叠.我在顶级doc块中以及属性/方法doc块中尝试了这个.我错过了什么吗？

可能的重复：
phpDoc 有没有办法将对象数组记录为参数？

我一直在搜索，并查看了 phpDocumentor 文档，但找不到是否有一种方法可以正确记录 @param 数组（如声明预期的键/值类型），该数组将被解析并包含在任何生成的文档中。

这会让我相信没有办法做到这一点，我将放弃使用该描述。

提前致谢。

在PhpStorm's设置中Editor/Inspections/PHP/PHPDoc/Missing @throw tag(s)有两个默认选择的选项：

• 忽略运行时异常
• 忽略逻辑异常

问题：为什么我要在创建 DocBlock 时忽略这些特定的异常？我想这需要有充分的理由，因为默认情况下会检查这些选项。

Logic Exceptions是像DomainException或这样的例外InvalidArgumentException。
Runtime Exceptions是例外，如RangeException或UnderflowException

注意：我使用的是 PhpStorm v8.0.3

我总是使用注释来声明返回类型.例如:

/**
 * @return SomeClass
 */
public function () { ... }

但现在我看到还有另一种方式:

public function () : SomeClass { ... }

题

我应该在这些之间做出选择,使用两者,还是他们有一些我应该注意的根本区别？

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

考虑以下 PHP 代码：

<?php

class ParentClass {
    /**
     * Says 'hi' to the world.
     * @return ParentClass Returns itself for chaining.
     */
    public function say_hi(){
        echo 'hi';
        return $this;
    }
}

class ChildClass extends ParentClass {
    /**
     * Says 'bye' to the world.
     * @return ChildClass Returns itself for chaining.
     */
    public function say_bye(){
        echo 'bye';
        return $this;
    }
}

$c = new ChildClass;
$c->say_hi()->say_b| <- type hinting won't suggest "say_bye" here

?>

这只是一个带有一些链接的琐碎类。扩展类没有类型提示，因为父类的文档块正在使用特定的类名，该类名没有子类的方法/属性。

假设我们确实想要类型提示功能，（如果没有，请留下这个问题 - …

php 文档块中以下内容的含义是什么：

#@+

zend框架代码中的示例：

/**#@+
 * @const string Version constant numbers
 */
const VERSION_10 = '1.0';
const VERSION_11 = '1.1';
/**#@-*/

我假设它用于对相关项目进行分组，但无法确定。

另外，它的语法非常奇怪——当它生成文档时它是如何翻译的？

我在ZF1的评论/文档中找到了一些特殊符号"#@ +"和"#@ - ".例:

/**#@+
 * @access protected
 */

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

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

这些是什么意思？

我在一些遗留代码中添加了一些注释,并且我遇到了PHPDocumentor的一个小问题.

这是一个例子:

/**
 * Constructs the Widget object
 * 
 * Basic constructor for the widget object.
 * Another line of pointless explanation, badly worded.
 *
 * @param  string   $id    The ID of the widget
 * @param  int      $size  The Size of the widget
 * @return void
 * @throws InvalidArgumentException
 */
public function __construct($id, $size) {
    if (!is_string($id) || !is_integer($size)) {
        throw new InvalidArgumentException('$id must be a string, $size an integer');
    }
    $this->id = $id;
    $this->size = $size;
}

我从命令行运行PHPDocumentor,并获得一个充满文档的可爱文件夹.

文档看起来很好,但我得到PHPDocumentor编译错误: …

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

/* @var $object FooClass */
$object = $someFunction->get('BarContext.FooClass');
$object-> // now will produce property and function hints for FooClass.

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

use Path\To\FooClass;

class Bar
{
    protected $foo;

    public function bat()
    {
        $this->foo = FactoryClass::get('Foo'); // Returns an instance of FooClass

        $this->foo //does not have hinting in IDE
    }
}

我已尝试过该类的docblock,或使用上面的内联注释protected $foo或将foo设置为实例.

到目前为止我找到的唯一解决方法是:

public function bat()
{
    $this->foo = FactoryClass::get('Foo');

    /* @var $extraVariable FooClass */
    $extraVariable = $this->foo;

    $extraVariable-> …

一般来说，在 PHP 中使用 DocBlock 是最佳实践之一。它对于以前的 PHP 版本（小于 PHP 7.3 或特别是 7.4）非常有用。它通知开发人员有关类属性类型、预期参数类型和方法返回值（在 PHP 中缺乏严格类型的情况下）。

假设在 PHP 5.6 中，代码如下所示：

namespace App\Service\Catalog\Category;

use App\Entity\Catalog\Category\Category;
use App\Repository\Catalog\Category\CategoryRepository;

class CategoryService
{
    /** @var CategoryRepository */
    private $categoryRepository;

    /** @var int */
    private $currentNestingLevel = 1;

    /**
     * CategoryService constructor.
     * @param CategoryRepository $categoryRepository
     */
    public function __construct(Category $categoryRepository)
    {
        $this->categoryRepository = $categoryRepository;
    }

    /**
     * @param $parentCategoryId
     * @return array
     */
    public function getCategoriesDataByParentCategoryId($parentCategoryId)
    {
        $categories = $this->categoryRepository->getByParentCategoryId($parentCategoryId);
        $categoriesData = [];

        foreach ($categories as $category) …