标签: phpdoc

PHPDoc 是 JavaDoc 对 PHP 的改编。通过注释中的正确语法，您可以使用它来记录事物的类型。然后，IDE 等工具可以使用该元数据。

这是一个使用“简单”字符串数组的示例。

/**
  * @param string[] $strings  This parameter is blah blah blah.
  */
public function foo($strings) {
    // ...
}

但是 PHP“数组”也可以用作映射（又名哈希表，又名字典）。以下是 PHP 文档 ( http://php.net/manual/en/language.types.array.php ) 中的示例：

$array = array(
    "foo" => "bar",
    "bar" => "foo",
);

现在假设我们修改我们的函数foo以接受$array上面的内容：字符串数组 => 字符串。

/**
  * @param ??????? entries  This parameter is blah blah blah.
  */
public function foo($entries) {
    // ...
}

$entriesPHPDoc 中应该如何表示的类型？

http://www.phpdoc.org/docs/latest/guides/types.html#arrays甚至没有提到该语言中存在的这种构造。

是否可以使用 PhpDoc 声明protected或private类@property？

/**
  * Class Node
  * @package app\models
  * @property string $name
  */
class Node
{

}

这可能是一个非常新手的问题，但是，您到底如何使用 phpDocumentor 通过 Laravel 生成文档？在我的 Laravel 项目中，目录中没有phpdocvendor/bin，并且尝试通过 Composer 安装 phpDocumentor 失败（如 GitHub 页面上的建议）。

我找不到任何有关它的最新资源，我唯一幸运的是phpDocumentor.phar从终端运行该文件，但最新版本立即失败。

我有一个特征，想输入提示 $this 来通知编译器它的类型：

trait MyTrait {
  public function myAwesomeFunction() {
    return new OtherClass($this); // warning: Expected MyAwesomeInterface, got MyTrait
  }
}

class OtherClass {
  public function __construct(MyAwesomeInterface $foo) { ... }
}

所以我想知道是否有相当于的东西，例如：

trait MyTrait {
  public function myAwesomeFunction() {
    /**
     *  @var $this MyAwesomeInterface
     */
    return new OtherClass($this); // no warnings
  }
}

这将使我能够通知编译器该特征的用户实现了我的接口。

请注意，特征无法在 PHP 中实现接口（请参阅为什么 PHP Trait 无法实现接口？）。

感谢您的任何帮助 ;-）

所以我使用 phpDocumentor 3 为我的 Laravel 7 项目生成文档，

我想知道我是否可以从 Laravel 提供此文档（静态文件），以便仅对授权用户可用。

我希望能够通过我的CI/CD更新文档，所以我不能只手动修改生成的文档。

我认为我可能必须为此编写自己的模板（https://docs.phpdoc.org/3.0/guide/guides/templates.html），但我不确定文档是否不完整或者我是否缺少一些东西，因为我不知道如何创建模板。有什么建议、指南或教程可以帮助我实现这一目标吗？
谢谢

我今天第一次尝试使用PHPDoc，但很快遇到了问题。

对于每1行变量声明，我至少有5行注释。例：

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

当然，收益是不错的-但这会将10行的配置文件转换为60行的文件。需要我一辈子来填写，但我还不相信它会在简单的单行代码中增加很多。

这也给我的工作流程带来了麻烦。在我需要进行彻底更改之前，一切都很好。有了我记录良好的文档块，我突然不再需要重构代码，而是需要重写所有这些繁琐的细节。等到你说完为止？哈！这样，文档将永远不会发生。

最重要的是-它迫使我在代码中间使用C风格的/ ** /注释。这使我在开发过程中发疯，因为它剥夺了按需注释掉大块内容的能力。现在注释掉一大段代码，我需要拉出类似：range，s / ^ /＃/;的代码。然后稍后撤消。烦人！

长话短说-我喜欢PHPDoc，我喜欢记录良好的代码-但是每一行代码只有5行注释！。有我缺少的功能吗？这是个常见的问题吗？

我在C中编写了一个PHP扩展,我想创建PHPdoc文档,以便我的用户在调用我的扩展时在他们的PHP IDE(在本例中为Netbeans)中获取内联文档.

理想情况下,我希望通过在PHP代码中嵌入PHPdoc来实现这一点,以便将实现和文档保持在一起.

假设可以将PHPdocs嵌入到C中,需要哪些额外的步骤才能使文档出现在Netbeans中(就像PHP代码的PHP代码一样)？

编辑:

O'Reilly编程PHP指的/* {{{ proto是在doc生成中使用的注释格式,虽然我不确定引用的脚本是否生成PHPdocs:

{{{proto line不仅用于在编辑器中进行折叠,还由genfunclist和genfuncsummary脚本解析,这些脚本是PHP文档项目的一部分.如果您永远不会分发您的扩展,并且没有野心将它与PHP捆绑在一起,您可以删除这些注释.

请考虑以下代码,我试图仅解析文件中的第一个phpDoc样式注释(不使用任何其他库)(文件内容放在$ data变量中用于测试目的):

$data = "
/**
 * @file    A lot of info about this file
 *          Could even continue on the next line
 * @author  me@example.com
 * @version 2010-05-01
 * @todo    do stuff...
 */

/**
 * Comment bij functie bar()
 * @param Array met dingen
 */
function bar($baz) {
  echo $baz;
}
";

$data =  trim(preg_replace('/\r?\n *\* */', ' ', $data));
preg_match_all('/@([a-z]+)\s+(.*?)\s*(?=$|@[a-z]+\s)/s', $data, $matches);
$info = array_combine($matches[1], $matches[2]);
print_r($info)

除了@todo之后的所有内容(包括bar()注释块和代码)被视为以下值之外,这几乎可以正常工作@todo:

Array (
    [file] => …

我正在记录我使用phpDocumentor在PHP中构建的程序.一切都很完美,但文档显示我有近100个错误,因为它正在读取我用来将文件上传到我的服务器的文件,但我没有创建.是否可以忽略那个给我所有错误的特定文件？这是我正在执行以生成文档文件的命令:

phpdoc run -d /var/www/html/myprogram/ -t /var/www/html/myprogram/documentation

我试图忽略的文件位于/myprogram目录内,如下所示:

/modules/module1/uploader.php

我找到了一些关于使用的信息--ignore,但我不知道是否指的是与目录特定的东西.

是否可以在index.php文件中写入指示phpDocumentor忽略某些文件的内容？

我想知道是否可以使用phpdoc来定义特定范围内的某个对象(仅在方法内)作为PHPUni的Mock,所以在该方法中我可以利用类型提示,例如 - > expected, - > methods等等就像你刚刚创建模拟而不将其解析为真正的类一样.

这是一个示范:

class someTest extends PHPUnit
{
    // here, usually we define the real class (SomeClass in this example)
    /** @var SomeClass */
    private $someMock;

    public function setUp()
    {
        $this->someMock = $this->getMock(SomeClass::class);
    }

    public function testSomethingInSomeClass()
    {
        // here i expect the type hint i defined in the beginning of this test class and its fine
        $a = $this->someMock->someMethodFromSomeClass();
    }

    private function setSomeMethodOnMock()
    {
        // but here i would like to have …