标签: phpdoc

如何记录phpDoc的类常量？我已经阅读了手册,但我找不到任何关于它们的信息.

还是刚刚处于'完成'状态？我已经在我的所有PHP项目中使用了PHPDoc多年,但我最近注意到PHPDoc网站上的最后一篇文章是从2008年开始的.所以我想知道是否该时间研究其他替代品如Doxygen.使用PHPDoc以外的东西有什么好处吗？

编辑:今天当Devw宣布发布Zend Framework 1.11.5时,开发区的有趣帖子他写道:

"Mike van Riel提议将我们的API文档生成转换为DocBlox.我们已经考虑将其用于ZF2,但是看到模板系统的灵活性,更重要的是我们在包装方面,速度和最小资源它用于生成输出,我们被出售.(API文档生成时间从80-100分钟减少到不到10分钟.)您可以自己查看结果." http://devzone.zend.com/article/13643

这就是为什么我担心,如果像Zend Framework这样的大型项目正在放弃phpDoc,那么在我看来,phpDoc的不活动不会被忽视.100分钟到10 ..这就是我喜欢听到的.

@ gms8994好打电话

*更新:事实证明DocBlox是伪装/重新品牌的PHPDocumentor2. http://www.docblox-project.org/

我正在使用PHPStorm IDE,并在运行代码检查时遇到麻烦.

我有一个返回对象集合的方法.它Collection本身就是一个对象,它有自己的方法,并实现了Traversable接口:

class Repository
{
    public function findByCustomer(Customer $user)
    {
        // ...
        return new Collection($orders);
    }
}

如果我将文档findByUser()返回a Collection,则代码检查会理解此对象上的方法,但不了解该集合包含的对象:

/**
 * @return Collection
 */
public function findByCustomer() { ... }

如果我记录findByUser()返回一个Order对象集合,代码检查现在可以理解集合中的内容,但不了解Collection自身的方法:

/**
 * @return Order[]
 */
public function findByCustomer() { ... }

有没有办法同时指定两者,像Java的语法？

/**
 * @return Collection<Order>
 */
public function findByCustomer() { ... }

用于记录接受可变数量参数的类方法的推荐方法是什么？

也许是这样的？

<?php

class Foo {
    /**
     * Calculates the sum of all the arguments.
     *
     * @param mixed [$arg1, $arg2, ...]
     *
     * @return float the calculated sum
     */
    public static function sum() {
        return array_sum(func_get_args());
    }
}

注意:作为一般规则,我想在可能的情况下应该避免这种类型的事情.话虽如此,仍然很难记录剩下的几个无法避免的案例.

有没有人使用其他任何东西来记录他们的PHP代码？PHPDoc? 是否有任何工具可以读取相同的文档语法,但提供更丰富的输出？

我想开始使用phpDocumentor,但我发现它很难 - 网络界面不能很好地播放,我无法让它解析示例文件

我可能没有正确设置它,我想要一个很好的一步一步的教程(即不是这一个)来检查我出错的地方,并希望得到它解析的东西

但我无法通过谷歌找到任何东西 - 任何人都可以建议任何好的教程或资源开始使用phpdoc？

非常感谢!

伊恩

编辑:谢谢你跳进去,ashnazg!这些是我遵循的步骤:

1. Pear没有在我的Mac上工作,所以下载了1.4.3版并将其解压缩到一个目录中
2. 在文件选项卡下的HD上指定样本文件2的绝对路径
3. 指定了一个世界可写的输出文件夹
4. 单击创建...在日志中创建的内容,创建的媒体文件夹但没有报告.日志总结"错误:没有解析"

我自从Pear工作并以这种方式安装了phpdoc; 可以通过命令行使用它,但任何关于什么可能与Web界面,以防止它解析文件的想法？似乎在所有其他方面都很开心.

编辑2:感谢您发布Developer.com文章的链接,Liz:这是非常基本但有用的快速入门.

我有几个完成的,较旧的PHP项目,包含很多我想用javadoc/phpDocumentor样式记录的包含.

虽然手动处理每个文件并被迫与文档一起进行代码审查将是最好的事情,但我只是出于时间限制,对工具感兴趣,以帮助我尽可能地自动完成任务.

我正在考虑的工具理想情况下具有以下功能:

• 解析PHP项目树并告诉我哪里有未记录的文件,类和函数/方法(即元素缺少相应的docblock注释)

• 提供一种方法,通过创建空结构轻松添加缺少的docblocks ,理想情况下,在编辑器中打开文件(内部或外部我不在乎),这样我就可以放入描述中.

可选的:

• 自动识别参数类型,返回值等.但这并不是真的需要.

有问题的语言是PHP,虽然我可以想象一个C/Java工具可能能够在经过一些调整后处理PHP文件.

感谢您的宝贵意见!

一些新的PHP 5.3功能,包括命名空间和匿名函数,与PHPDocumentor不兼容,即使使用最新版本也是如此.例如,它只是在遇到"没有名称的函数"时引发错误,即闭包.那么,是否还有其他开源工具可以从PHP 5.3代码中的Javadoc样式注释生成API文档(最好是HTML)？

TL;博士

注释(在PHPDoc中)通过实现的函数的正确方法是什么__callStatic？更重要的是:有没有办法让NetBeans 和 PHPStorm理解这些是静态方法？

动机

如果你想要更大的图片,这就是我对这个问题的看法.

问题:在我目前的项目中,我们有很多类应该是单例(DB代理等).不用说,我们至少有几百require_once并$foo = new FooProxy();线.

解决方案:我创建了一个Loader类来解决这个问题,使用__callStatic魔术方法,所以我们可以说$foo = Loader::FooProxy();.它非常适合我们的目的,但是:

问题:这种方式在团队中使用的IDE中显然没有类型提示.

解决方案:每个模块定义一个子类Loader,添加仅路由到的方法__callStatic.

问题:为了自动完成而添加实际解释的代码是不可接受的(这可以争论,但让我们暂时接受它).

解决方案:我们不添加任何实际方法,只需在PHPDoc中声明方法如下:

<?php
/**
 * @method FooProxy FooProxy()
 */
 class BarLoader extends Loader {}
?>

问题:FooProxy不是静态方法.以下所有内容都不会使其成为静态:

<?php
/**
 * @static
 * @method FooProxy FooProxy()
 */

///////////////

/**
 * @static @method A A()
 * @method static A A()
 * @method A …

当你在类或函数之前Enter输入后按下"自动完成"时,我会搜索一下更改PHPDoc在PhpStorm中使用的名称和邮件/**的方法.

示例:

/**
 * Class DepartmentType
 *
 * @author Foo Bar <foo.bar@email.com>
 */
class Foo
{

因为,这个名字和这封邮件不是我在项目中使用的git的名称和邮件配置.我没有找到任何地方来更改此默认值...

有人有想法吗？