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.
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.");
}
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
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.
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.
Related
I'm currently building up some phpdoc for a restful API - and I took to using the #param doc syntax for notating required params over POST.
However, after generating the phpdoc, I noticed that it refuses to list these parameters unless they match exactly with input variables into the method itself.
#uses and #see don't look good nor make much sense here when it comes to the phpdoc output. The style/look of the doc is perfect with the #param functionality.
Is there any way to override the rules put in place by PHPDoc, and allow it to generate #param blocks in the documentation, even if the param doesn't exist in the method itself?
If you want to document your API, I suggest you use proper tools like API Blueprint or Open API Spec.
And by using Swagger, you can even use annotations (which is what you apparently want) to document the API and in turn, generate the documentation out of it.
Just don't use PHPdoc for it, because that's just mixing concepts altogether.
Alright, I'm going to answer this with the solution I've found - I appreciate all the "do not do that" answers, but still hope that someone who finds themselves in a similar situation to myself ala "this needs to be done immediately without changing the format, and we cannot allot any time to this" will find it useful in the future.
You can maintain using the #param syntax if you initialise the method with the param specified, and simply set it to null - ensuring it doesn't break any existing calls.
/**
* Remove a group
*
* #param int $pricing_group_id Required
* #return mixed JSON array with remaining groups
*/
public function remove($pricing_group = null) {
....
}
Your PHPDoc output will now show the param type, name, and description as normal.
Keep in mind that this is not good practice - nor is it even remotely correct practice. But it'll work until you can convince a higher-up to allot you enough time to rebuild the existing documentation on a more suitable platform.
You can do this by utilizing "optional". IE:
#param string $variable (optional) Blah.
See other examples at https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html .
This is to be used in the use case of when a parameter is optional, unlimited parameters, etc.
You might consider using a "custom" tag, maybe #parameter, so that it is listed "as is". You won't get the same hyperlink behavior for class names as the param tag provides, but you won't be limited by the lack of parameters in the code signature itself. Maybe use an inline link tag in the parameter description that points to the class type of the parameter. Otherwise, the uses, see, or link regular tags can be on separate lines as convenient links to the classes that are your parameter types.
There is currently no way to disable the internal behavior of "actual code signature overrides param tags" logic.
I believe you can use the same approach for documenting virtual methods as a workaround, i.e. via a #method entry in the phpDoc header for the class.
E.g.:
/**
* ...
*
* #method mixed remove(integer $pricing_group_id) Remove a group and return a JSON array with remaining groups.
*/
class YourClass {
...
// see class header for phpdoc entry
public function remove($pricing_group = null) {
....
}
}
A downside is that (to my knowledge) this approach does not provide a means to enter explicit description entries for the method's parameters and return value.
I'm using eclipse to build my php applications and the Source > Generate Element Comment function for automatically creating doc blocks.
I'm wondering a bit about the format because the return type is set as full-qualified class name but the parameters not.
Is this a bug of the IDE or is it the common convention?
Here's an example:
/**
* Executes the given service.
*
* #param string $serviceClass
* #param ParametersInterface $inputParams
*
* #return \ZF\Hal\Entity
*/
And I have the following uses:
namespace MyApp;
use ZF\Hal\Entity;
use Zend\Stdlib\ParametersInterface;
It's most likely just a behavior oddity in Eclipse, where the auto-recognition code for parameters is possibly not the same code that auto-recognizes returns. I would bet the parameter recognition is more naive, in that it probably keys specifically off your method signature. So, if your method signature is
public function executeService(string $serviceClass, ParametersInterface $inputParams)
then the auto-doc probably gets exactly just the ParametersInterface you have in the code.
However, if you wrote the code this way
public function executeService(string $serviceClass, Zend\Stdlib\ParametersInterface $inputParams)
then I'd bet the auto-doc would show the fully namespaced name.
It wouldn't hurt to report it to Eclipse (if it's not already been reported).
This may happen if you have use ParametersInterface; with it's path on top of file, so PHP doc takes it into account, but you don't have use ZF\Hal\Entity, so it's inserted in #return with full path.
In PHPStorm it works like this, so probably in Eclipse it works the same
I have some PHP code that is documented with Doxygen. In this code, there are a number of hooks, which are functions that my code calls, but the functions themselves are defined by the users of this code.
I want to document the hooks, but because the functions don't exist in my code (the users define the functions, my code just calls them) there is nowhere for me to attach the Doxygen comments to - unless I define a fake function.
Is there some way I can avoid defining this fake function? If I were using C I could define the function but use #ifdefs to hide it from the compiler (but still have Doxygen see it), but I'm not sure what the equivalent is in PHP. Ideally I'd want something that wouldn't result in any additional effort on the part of the PHP parser.
Any suggestions? This is what I am trying to document, and how I have it now with the fake function:
/// This is an example hook.
/**
* Register it with $hooks['example'][] = 'your_function_name_here';
*
* #param string $dummy
* Dummy parameter.
*/
function hook_example($dummy) { }; // fake function for Doxygen
If you want other programmers to implement your hooks use OOP interfaces and abstract classes. This will sanitize your code.
As a side effect, Doxygen will be very happy to document the abstract methods.
Since PHP doesn't support #ifdef blocks, I think the only way this can be done is to take the comments and fake function declarations and put them in another .php file. Configure Doxygen to include this new file, but don't include() it anywhere in the rest of the code.
Then the fake functions will appear in the documentation, but the PHP parser will never know about them.
I've really only just discovered that you can use /** #blah */ comments to specify certain things, but is it possible to create sections in code?
Like:
/** Start Section "Blah" **/
$result = doSomething();
echo $result;
/** End Section "Blah" */
No PDT can't do that. Generally expandable code sections are identified by function and class method bodies.
If you think you need artificial sections identified by comments I recommend to rather think about reorganizing your code into more fine grained files, function, classes and methods that can be easily documented using PhpDoc (which is the standard PDT uses).
these sections
/**
* here goes your text
* #author Nanne
* /
Are based on javadoc: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Look at this page where a documenter for PHP is described. I don't know what standard is used in Eclipse, but I'm guessing they're all rather alike:
http://www.phpdoc.org/
Is is mostly based on commenting certain parts of code, e.g. classes, functions and variables. As far as I know there is no special code for "sections". The reason I think this, is that you are 'supposed' to make a documentation from this, with classes, it's methods etc. There is no special way to represent "sections" in a documentation like that.
But do read above links, it'll clear up a lot!
In PHP you can use sections to separate pieces of code. Syntax is like this:
Blah:{
$result = doSomething();
echo $result;
}
These were used by goto style procedural programming before object oriented programming was used (classes and instances). Using these sections and goto statements is very bad practice and should be shunned by any developer.
https://www.php.net/manual/en/control-structures.goto.php
I think my eclipse's ctrl+clicking links might benefit greatly...
Edit: I'm using eclipse PDT.
Edit 2: I'm very happy with the solution of putting docblocks before functions (and variables) with an #return or #var statement, I've just updated the documentation of my app and now eclipse is showing me what functions are available to what objects!
Awesome.
// [...]
/**
* Return the Request object
*
* #return Zend_Controller_Request_Abstract
*/
public function getRequest()
{
return $this->_request;
}
// [...]
works perfectly with Eclipse PDT. Which plugin do you use?
Short answer: no.
Long answer: consider adding docblocks with #return declarations.
The only way to hint return type in PHP is to use a good IDE like Eclispe PDT or Zend Studio with standard comment block. PHP simply can n not predict return type because it is dynamically typed language so type checking is done in the run time unlike for the statically typed languages like C#, JAVA and C++.