Documenting a PHP extension with PHPdoc

Question

I've written a PHP extension in C, and I want to create PHPdoc documentation so that my users will get inline docs in their PHP IDE (in this case, Netbeans) when calling my extension.

Ideally I'd like to do this by embedding the PHPdocs in the C code, to keep implementation and documentation together.

Assuming it's possible to embed PHPdocs into the C, what extra steps are needed to make the documentation appear in Netbeans (as it would for PHPdocs of PHP code)?

edit:

O'Reilly Programming PHP refers to the /* {{{ proto comment format being used in doc generation, though I'm not sure if the referred scripts generate PHPdocs:

The {{{ proto line is not only used for folding in the editor, but is also parsed by the genfunclist and genfuncsummary scripts that are part of the PHP documentation project. If you are never going to distribute your extension and have no ambitions to have it bundled with PHP, you can remove these comments.

Answer 1

Hi, 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

Answer 2

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

Answer 3

I think it is possible to use Reflection API to generate the prototype file, though I could not find existing code that does exactly that.