CODEWITHSUNDEEP
phpnetbeansphpdocphp-extension
John Carter
John Carter

Reputation: 55369

Documenting a PHP extension with PHPdoc

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.

Upvotes: 4

Views: 2988

Answers (4)

Eugene Manuilov
Eugene Manuilov

Reputation: 4361

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.

Upvotes: 0

StasM
StasM

Reputation: 11082

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.

Upvotes: 0

John Carter
John Carter

Reputation: 55369

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

Upvotes: 5

opHasNoName
opHasNoName

Reputation: 20736

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

Upvotes: 4

Related Questions