使用 PHPdoc 记录 PHP 扩展

发布于 2024-07-26 15:23:55 字数 715 浏览 6 评论 0原文

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

理想情况下，我想通过将 PHPdocs 嵌入 C 代码中来实现此目的，以将实现和文档放在一起。

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

编辑：

O'Reilly 编程 PHP 指的是 / * {{{ proto 注释格式用于文档生成，但我不确定引用的脚本是否生成 PHPdocs：

不仅使用了 {{{ 原型行用于在编辑器中折叠，但也是由 genfunclist 解析并 genfuncsummary 脚本的一部分 PHP 文档项目的一部分。如果你永远不会分发你的延伸并且没有野心将其与 PHP 捆绑在一起，您可以删除这些评论。

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

梦中的蝴蝶 2024-08-02 15:23:55

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

通过这种方式，类型完成和内联文档可以工作，但 PHP 不会因函数的多个声明而感到困惑。

这看起来有点老套，因为最好将文档与实现放在同一个文件中，但它实际上似乎是正确的方法，因为这就是内置函数和扩展的记录方式 - 请参阅 ~/ netbeans-6.7/php1/phpstubs/phpruntime/*.php

例如：

在 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.");
}

One approach that works is to have a PHP file with stub functions with the appropriate PHPdocs, then DON'T include it in the PHP application, but DO add it to Netbean's PHP include path (in File->Project Properties->PHP Include Path).

This way type completion and inline docs work, but PHP isn't confused by multiple declarations of the function.

This seems a bit hacky, since it would be good keep the docs in the same file as the implementation, but it does actually seem to the correct approach, since that's how the built in functions and extensions are documented - see ~/netbeans-6.7/php1/phpstubs/phpruntime/*.php

eg:

In the C file:

PHP_FUNCTION(myFunctionStringFunction)
{
// extension implementation
}

And then in a PHP file, the stub declaration:

/**
 * 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.");
}

回复收藏 0 原文

故事与诗 2024-08-02 15:23:55

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

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

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

you only need to use the right TAGS inside your Comments.

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

You can find all available tags on the documenation
PHPDoc

回复收藏 0 原文

绝影如岚 2024-08-02 15:23:55

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

回复收藏 0 原文

时光无声 2024-08-02 15:23:55

正如扩展骨架中所写：

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

上一行适用于 vim 和 emacs，因此它可以正确折叠
并在源代码中展开函数。看看对应的标记就可以了
在函数定义之前，函数的目的也是
记录在案。为了方便大家，请遵守本约定
其他人编辑您的代码。

As written in extension skeleton:

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

The previous line is meant for vim and emacs, so it can correctly fold
and unfold functions in source code. See the corresponding marks just
before function definition, where the functions purpose is also
documented. Please follow this convention for the convenience of
others editing your code.

回复收藏 0 原文

~没有更多了~