标签: docblocks

在使用notepad ++和sublime编写许多快乐的岁月后,我被建议给PHP IDE一个机会.我正在尝试phpStorm,看起来不错.代码完成和文档是一个很好的功能,但是当使用魔术方法时,对我来说并不奏效.是否有工作让phpStorm了解魔术方法中发生了什么？

我们的情况是这样的:

abstract class a {
    public static function __callStatic($method,$args)
    {
        if(strpos($method,"get_by_") === 0)
        {
            //do stuff
        } elseif(strpos($method,"get_first_by_") === 0) {
            //do stuff
        } elseif($method == "get_all") {
            //do stuff
        }
    }
}

class b extends a {
    // some more stuff
}

b::get_by_user_id(27);
b::get_first_by_id(156);
b::get_all();

神奇的callStatic方法允许我们通过构成函数调用的一个或多个参数来获取对象的集合.

我看到在这些情况下有一个@method语句可用,但phpStorm只是获取了这些语句中的第一个.此外,我只能将返回类型设置为混合,因为我更愿意将其设置为调用它的任何类(在我的示例中为b).

非常感谢任何想法或建议,谢谢.

在我创建一个方法后,我用它/**<enter>来生成DocBlock.它会自动填充@param和@return执行该功能.例:

/**
 *
 * @param type $str
 * @return type 
 */
public function strlen($str){
    return strlen($str);
}

如何自定义生成的块,以便它也可以填充@author并最终生成/**<enter>

/**
 *
 * @param type $str
 * @return type 
 * @author John Doe <john@doe.com>
 */
public function strlen($str){
    return strlen($str);
}

谢谢

有没有办法让phpStorm更新docblock的内容？例如,如果我有以下代码

//-------------------------------------------------------------------------
/**
 * @param string $url
 * @return $this
 */
public function setBaseUrl($url)
{
    $this->baseUrl = $url;
    return $this;
}

并添加另一个参数

//-------------------------------------------------------------------------
/**
 * @param string $url
 * @return $this
 */
public function setBaseUrl($url, $anotherParameter)
{
    $this->baseUrl = $url;
    return $this;
}

有没有办法让phpStorm在我的docblock中创建@param $ anotherParameter？(在一次击键或菜单选择中)？

让我们说我有一个函数(显然是一个简单的例子):

public function dot(){
    return implode('.', func_get_args());
}

现在我知道我可以修改它

public function dot(array $items){
    return implode('.', $array);
}

但有些功能不是一种选择.那么,您如何使用docBlock记录该函数的第一个版本,以便IDE可以解释它可以接收无限制的参数？

我见过一些使用的方法:

/**
 * Joins one or more strings together with a . (dot)
 * @param string $string1
 * @param string $string2
 * @param string $_ [optional]
 * @return string
 */
public function dot($string1, $string2, $_ = null) {
    return implode('.', func_get_args());
}

在IDE中看起来像

但这对我来说就像是一个黑客攻击,有没有办法只用docBlock来做到这一点？

是否有标准方法在Doctrine项目的docblock注释中记录Collection内的预期实体类？就像是:

/**
 * @var Collection<User>
 */
protected $users;

看起来PHPDoc现在是docblock注释的事实标准,但是我找不到这个用例的任何提及.

我想为一些项目构建一些规模较小但高度定制的文档站点.PhpDocumentor非常棒,但它很重.我考虑过尝试调整模板,但是在花了几分钟的时间研究之后,我认为这将是太多的工作.

理想情况下,我希望看到一些东西,我可以传递一堆文件,并让它返回所有的文件,类和属性和方法,以及他们的元数据,以便我可以构建一些简单的模板基于数据.

是否有任何DocBlock解析器项目可以帮助我完成这项任务,还是我重新发明了那个轮子？

我很困惑何时在使用nullPHPDoc描述变量时使用as作为类型.类型提示是否应该描述外部呼叫者预期和遵守的希望和期望,或者他们是否应该记录变量的所有可能类型,即使希望它在实践中是一种非常特定的类型？

示例1:默认值.以下函数仅需要非空值.但是,如果没有传递任何值,则默认为null并明确检查该值作为确定是否传递任何内容的方法,并为该情况返回特殊值.希望没有外部调用者将传递除整数之外的任何内容.应该null在@param下面的类型中使用,还是应该只指定,int因为如果传递任何东西,我们想要传递的是什么？

/**
 * @param int|null $bar
 */
function foo($bar = null) {
  if(is_null($bar)) { 
    return 'ABC';
  }

  return doSomething($bar);
}

示例2:实例属性.我们只想要$ bar来包含整数.也就是说,如果没有为bar设置任何内容,则此实例属性的默认PHP值为null.我是否需要考虑使用$ bar的每个地方,可能的null类型如下所示？

class Foo {
  /**
   * @var int|null
   */
  public $bar;

  /**
   * @param int|null $bar
   */
  public setBar( $bar) {
    $this->bar = $bar;
  }

  /**
   * @return int|null
   */
  public function getBar() {
    return $this->bar;
  }
}

基本上我发现自己几乎每个人都乱扔垃圾@param并@var声明,|null因为从技术上来说它可能就是那个价值.但在实践中它不应该.我是否应该期望我的几乎所有类型都包含 …

我对PHP dockblocks非常熟悉,因为它是我过去15年来的工作.

/**
  * Description
  *
  * @tag bla bla
  * @tag more bla bla
  */

我想要了解的是,对于Delphi和/或FreePascal,是否存在类似的标准.

从我对很多代码的分析我从未见过,但我可能是错的.

我可以在FakerPHP/Faker包中看到这个 PHPDoc 块，但我不知道这是什么@template意思？您可以在该行的包的主分支中找到它

/**
 * @template T of Extension\Extension
 *
 * @param class-string<T> $id
 *
 * @throws ContainerExceptionInterface
 * @throws Extension\ExtensionNotFound
 *
 * @return T
 */

我真的很难让phpDocumentor 2工作.

我有几个程序风格的文件,必须记录.我发现这是唯一使用页面级别的docblock,但似乎它们在phpDocumentor版本2中不再正常工作.

stackoverflow上的一个相关问题表明其他人遇到了同样的问题.在这个问题中有两个建议:

1. 将a添加namespace到应记录的文件中
2. 从phpDoc问题910开始使用模板abstract或new-black

不幸的是,我无法找到任何一个工作.

1. 当我添加命名空间时,命名空间本身会显示在文档中,而不会显示在docblock的内容中.
2. 当我选择另一个模板(我试过zend,abstract和new-black)与phpDoc 2的phar版本时,我得到错误PHP Warning: XSLTProcessor::transformToUri(): No stylesheet associated to this object in phar.显然这是一个已知的问题.

编辑:

我更进了一步.我安装了phpDocumentor的PEAR版本,并尝试了每个可用的模板.但我还远未达到目标:生成的文档中的页面级docblock.
模板分为两类:

• clean,responsive,responsive-twig和old-ocean:他们这样做所产生的文档中未输出页面级的文档块.
• abstract,new-black和zend:他们有一个doc by file部分,它显示了预期的文件级文档.但是他们错过了几个资源(.js文件和图像),因此它们看起来完全相同,并且无法正常工作(导航窗格没有展开 - 折叠行为).我查看了他们的git存储库,文件似乎甚至错过了.

在这一点上,我只是想知道我是否正在寻找正确的方向:似乎不可思议,由于phpDocumentor 2中的主要回归和错误,不可能有文档显示文件级docblocks.

如果我真的走错了路,请建议我如何从PHP项目中获取有价值的文档.如果我走在正确的轨道上,请帮助我理解我所缺少的拼图中的重要部分.