使用 PHPdoc 记录 PHP 扩展答案

【问题标题】：Documenting a PHP extension with PHPdoc使用 PHPdoc 记录 PHP 扩展
【发布时间】：2010-11-08 23:31:17
【问题描述】：

我已经用 C 语言编写了一个 PHP 扩展，我想创建 PHPdoc 文档，以便我的用户在调用我的扩展时可以在他们的 PHP IDE（在本例中为 Netbeans）中获得内联文档。

理想情况下，我想通过在 C 代码中嵌入 PHPdocs 来做到这一点，以将实现和文档保持在一起。

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

编辑：

O'Reilly Programming PHP 指的是在文档生成中使用的/* {{{ proto 注释格式，尽管我不确定所引用的脚本是否会生成 PHPdocs：

{{{ proto 行不仅用于用于在编辑器中折叠，但也是由 genfunclist 解析和 genfuncsummary 脚本的一部分 PHP 文档项目的。如果你永远不会分发你的扩展和没有野心将它与 PHP 捆绑在一起，您可以删除这些 cmets。

【问题讨论】：

只是为了澄清：您已经用 C 编写了一个 php 扩展（例如 php_hsqldb，一个访问 hsqldb 的扩展）。并且您想要从 C 代码中的注释创建的文档。到目前为止？
是的。希望编辑的问题更清楚。

标签： php netbeans phpdoc php-extension

【解决方案1】：

一种可行的方法是使用适当的 PHPdocs 生成一个带有存根函数的 PHP 文件，然后不要将其包含在 PHP 应用程序中，而是将其添加到 Netbean 的 PHP 包含路径（在 File->Project Properties->PHP Include Path 中）。

这种类型完成和内联文档的工作方式，但 PHP 不会被函数的多个声明混淆。

这似乎有点 hacky，因为最好将文档与实现保存在同一个文件中，但它实际上似乎是正确的方法，因为这就是记录内置函数和扩展的方式 - 请参阅 @987654322 @

例如：

在C文件中：

PHP_FUNCTION(myFunctionStringFunction)
{
// extension implementation
}

然后在 PHP 文件中，存根声明：

/**
 * My docs here
 * @param string $myString
 */
function myFunctionStringFunction($myString)
{
  die("Empty stub function for documenation purposes only.  This file shouldn't be included in an app.");
}

【讨论】：

我注意到了同样的事情......例如。在 PDT (Eclipse) 中，有一大块 PHP 文件专门定义诸如“核心”PHP 函数，甚至是常量等内容。

【解决方案2】：

您只需要在您的评论中使用正确的标签。

 /**
 * Returns the OS Languages for an Subversion ID
 *
 * @access  public
 * @param   int         $subVersionId   Subversion ID
 * @return  array       $results        Languages for Subversion ID
 */

您可以在文档中找到所有可用的标签 PHPDoc

【讨论】：

澄清一下，我说的是 C 扩展，而不是普通的 PHP 代码。

【解决方案3】：

我认为可以使用 Reflection API 来生成原型文件，尽管我无法找到可以做到这一点的现有代码。

【讨论】：

【解决方案4】：

如扩展骨架中所写：

/* {{{ */ and /* }}} */

上一行是针对 vim 和 emacs 的，所以它可以正确折叠并在源代码中展开函数。只看对应的标记在函数定义之前，函数的目的也是记录在案。为方便起见，请遵守此约定其他人正在编辑您的代码。

【讨论】：