phpdoc
Correct syntax for inheritDoc in phpDocumentor
A child element should be automatically inheriting pretty much everything from its parent docblock without needing this tag. Otherwise, all your implementation methods would have to be documented all over again without gaining anything by the original interface’s documentation. Simply, an inherited element without a docblock should automatically inherit everything from its parent’s docblock. The … Read more
Best way to document (phpdoc) generators (methods that yield)
I went with @return Generator|SomeObject[], where SomeObject is the thing being yielded. PhpStorm handles this well too, as it now normally hints Generator methods and when iterated it hints SomeObject methods. (Still, I would prefer a native @yield.)
Should I use @return self, this or the current class? [closed]
There is a PHP Standards Recommendation (PSR) currently in draft (PSR-5) that proposes @return $this is used in order to indicate that the same instance is returned. $this, the element to which this type applies is the same exact instance as the current class in the given context. As such this type is a stricter … Read more
PHPDoc: @return void necessary?
If it makes it clear for the documentation, then leave it in, but it isn’t strictly necessary. It’s an entirely subjective decision. Personally, I would leave it out. EDIT I stand corrected. After a little googling, the wikipedia page says: @return [type description] This tag should not be used for constructors or methods defined with … Read more
What is the correct way to write PHPDocs for constants?
The PHP-FIG suggests using @var for constants. 7.22. @var You may use the @var tag to document the “Type” of the following “Structural Elements”: Constants, both class and global scope Properties Variables, both global and local scope Syntax @var [“Type”] [element_name] [<description>]
Variable type hinting in Netbeans (PHP)
A single line is all you need: /* @var $varName Type_Name */ See this article in the NetBeans PHP Blog: https://blogs.oracle.com/netbeansphp/entry/defining_a_variable_type_in Note: At least, in version 8.2; The key seems to be: The single asterisk (/* instead of /**). Placing the type after the variable name. Having nothing before and after the type-hinting (except white-space, … Read more
Best way to document Array options in PHPDoc?
This is how I do it instead: /** * Class constructor. * * @param array $params Array containing the necessary params. * $params = [ * ‘hostname’ => (string) DB hostname. Required. * ‘databaseName’ => (string) DB name. Required. * ‘username’ => (string) DB username. Required. * ‘password’ => (string) DB password. Required. * ‘port’ … Read more