标签: phpdoc

我搜索了 PhpStorm 的首选项、文档和 Google，但没有结果。

有没有办法默认禁用 PhpStorm 的“提取方法”对话框中的“生成 PhpDoc”选项？

如何在返回数组的PHP方法的文档中指定键的类型？

例如，我将其用于对象数组@return MyClass[]。

但是我想评论一个数组array( 'string' => array( MyClass ) )，这可能吗？

我使用简短的语法来定义类的成员变量，而不是

private $a;
private $b;
private $c;

我用

private
    $a,
    $b,
    $c;

现在我使用 PHPDoc 告诉 IDE 每个成员的类型，如下所示：

/** @var classA */
private $a;
/** @var classB */
private $b;
/** @var classC */
private $c;

但是，这不适用于简短语法：

private
    /** @var classA */
    $a,
    /** @var classB */
    $b,
    /** @var classC */
    $c;

我究竟做错了什么？

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

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

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

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

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

有没有办法记录特定函数调用exit()？

用例是我们有一个函数负责处理重定向（检查已发送的标头、设置响应代码等），然后关键地调用exit(). 不幸的是，PHPStorm 不知道这个特定的函数会终止执行，因此建议进一步警告，好像这个函数已经返回，但实际上它永远不会返回。

我来自一种严格类型化的编程语言，它有一个名为“ANY”的类型。

因为 PHP 是松散耦合的，所以我的 PhpDoc 需要某种类型的提示，说明变量、参数或返回值可以是任何类型。目前我必须写一些类似的东西：

@var string|int|bool|array|object $someVariable

如果我可以这样写，它会让我的生活更轻松，代码也会更容易阅读：

@var any $someVariable

我实际上在很多情况下都遇到了这个问题 - 在过去的几个月里，到目前为止已经超过 20-30 次，因为我使用 PhpStorm，它向我显示警告，某些方法需要其他类型的参数类型，要么是因为我忘记了将它明确地放在类型列表中，或者因为我使用的是在 Eclipse 中编写的代码，它没有对我自称的“任何”类型显示任何警告。

我的问题：有没有办法告诉 PhpStorm，当我说any我的意思时，string|any|bool|array|object或者是否有其他类型的提示可以这么说？我也很好奇我是否是唯一一个遇到这个问题的人，或者是否还有其他人像这样工作。

考虑这个代码：

class ParentClass {

    public static function generate($className = __CLASS__){
        if(!$className) return new self();
        else return new $className();
    }
}

class ChildClass extends ParentClass {

    /**
     * @param string $className
     * @return ChildClass
     */
    public static function generate($className = __CLASS__) {
        return parent::generate($className);
    }
}

var_dump($ChildClass::generate()); // object(ChildClass)[1]

ChildClass::generate()返回ChildClass我使用它的任何地方的实例，因为我从不提供$className参数。问题是我的 IDE 给了我一个关于parent::generate()调用与记录的返回类型不匹配的警告：

我想通过向父方法添加文档来消除此警告。我可以：

@return ParentClass | ChildClass

将这个添加到父方法中是可行的，但这并不实用，因为有很多子类，而且将来可能会有更多。我已经尝试了以下两种方法：

@return static
@return $className

但这并没有使警告消失。是否有 PHPDoc 批准的方法来指示调用子类将始终返回？或者——更准确地说——$className将返回一个类型的类？如果没有，有没有一种方法可以在我的 IDE 中工作？( PhpStorm 2017.2)

更新

@gogaz …

想象一下，我们有一个带有可选的可为空参数（PHP 7.0）的方法，如下例所示：

/**
 * @param Type1 $foo 
 * @param Type2 $bar
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

不幸的是，PHPDoc 文档并不清楚，将第二个参数标记为可选和可为空的正确方法是什么。

通常我使用“Type2|null”表示法：

/**
 * @param Type1 $foo 
 * @param Type2|null $bar
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

实际上这是我更喜欢的方式，因为它明确描述了所有可能的类型。但是我从文档中听到了不明显的抱怨，无论参数是否可选。

我知道，像接缝一样，非官方约定“（可选）”

/**
 * @param Type1 $foo 
 * @param Type2 $bar (optional)
 */
 function myFunction(Type1 $foo, Type2 $bar = null)
 {

 }

我不喜欢这种方法，因为从技术上讲，您可以明确提供 NULL 作为第二个参数。从phpdoc中不清楚。

一般来说，我什至可以一起使用它们：

 * @param Type2|null $bar (optional)

但它看起来并不好看，恕我直言。

你能给我一些反馈，或者更好的是，一些指向相应编码标准/风格指南的链接吗？

我很想找到一种方法（如果这甚至可能？）让 PhpStorm 自动完成我的Factory类生成的代码，而不必每次我从中提取类时都编写 PHPDoc。

这是我的代码：

<?php
class Factory
{
    public function getManager(string $class)
    {
        // if in cache ... returns

        // not in cache > init
        $manager = new $class();
        $this->doStuff($manager);
        return $manager;
    }

    public function doStuff($manager) {}
}

$factory = new Factory();
/** @var DateTime $dtClass */
$dtClass = $factory->getManager(DateTime::class);
$dtClass->getTimestamp();

因此，为了自动完成并消除 PhpStorm 警告，我必须在每次getManager()调用相应类后添加该行。

/** @var DateTime $dtClass */

我想知道 PHPDoc、PhpStorm 帮助文件或任何东西是否可以帮助做到这一点？

    /**
     * @template T
     * @param string $class <T>
     * @return <T>
     */ …

我在 PhpStorm 中创建了一个 PHP 类，并允许 IDE 为该类自动生成 DocBlock。它包含一个与文件命名空间完全匹配的包标记，如下所示：

<?php
namespace frontend\controllers;

/**
 * Class MethodController
 * @package frontend\controllers
 */
class MethodController extends BaseRestController 
{
}

我目前不关心生成 PHPDocumentor 输出，但我可能想在某个时候，所以我想了解如何@package使用。令我惊讶的是 PHP_CodeSniffer 为这个标签提供的消息：

[phpcs] 包名“frontend\controllers”无效；考虑“前端控制器”

我需要创建某种目录来满足 PHP_CodeSniffer 吗？

另一个令人困惑的转折是来自PHPDoc 网站的引用：

如果，一刀切，逻辑和功能细分相同，则不建议使用@package 标记，以防止维护开销。

如果我理解正确，那么使包与命名空间完全相同没有任何好处。为什么 PhpStorm 提供这个标签？