Given the phpDoc manual, I cannot find explanation about that
#property-read
#property-write
but only of #property.
What do they do?
Here's a good explanation on magic properties.
Basically, #property-write is interpreted - as the name suggests - as a write-only property. The code completion in Eclipse, for example, makes use of this. If your magic property foo is declared "write-only", it wouldn't show up in code completion, when you type $a = $this->f.
The #property tag is what's documented in the phpDocumentor manual. This tag is used only in a class docblock to document a "magic" property/variable, i.e. one that is not defined in the code, and therefore can't be "docblock'd".
Now, when you want to highlight that a particular "magic variable" is read-only (not writable), you'd use #property-read. If you have a "magic variable" that is write-only (not readable), you'd use #property-write. Granted, I have trouble imagining write-only variables that can't be read, but since it's technically possible to do it, #property-write is available for you to document it.
These two "subtags" of #property are explained farther down on the #property page that you linked to above.
Related
an old fashioned example:
/**
* #param string $a - test parameter
*/
public function test($a)
{
}
but now that Php has types, I would write:
/**
* #param $a - test parameter
*/
public function test(string $a)
{
}
since it has a parameter, so adding "string" to phpdoc is verbose.
"Necessary" depends on what you're using to parse the annotation (if anything)*
If this is PHPDocumentor itself, you'll want to stick with the standard that it prescribes. Even if it works without the type now, there's no guarantee that a future version will, and as mentioned in Alex Howansky's answer, the type is currently defined as mandatory. From their manual:
With the #param tag it is possible to document the type and function of a single argument of a function or method. When provided it MUST contain a Type to indicate what is expected; the description on the other hand is OPTIONAL yet RECOMMENDED in case of complicated structures, such as associative arrays.
PHPStorm (at least the version I have in front of me) acts a bit strangely if you leave out the type-hint in a parameter. If I use
* #param $a Some useful comment about my parameter
then I get a warning about Undefined class Some. Apparently it's taking the first word other than the #param annotation and the variable name, and assuming that's the type. I can't find a reference to this behaviour in the phpdoc manual (providing the type after the variable), so that could itself be non-standard. Interestingly, if the first character after the variable name is a hyphen (as in the example in your question), then the warning is supressed.
I've seen a lot of code recently that leaves out the annotations entirely, and relies on the language's internal type-hinting (both parameter and return) to do the job. This is perfect, as long as you don't need to add a description to any of them. PHPStorm will warn you about missing parameter annotations the moment you provide any (but not all) of them, which means if you want to provide a comment for one then you'll need to add the rest, commented or not.
You mention verbosity in your question, and if all you're concerned about is human readability then by all means leave out the type. Phpdoc itself has a standard, but you're absolutely not bound by it. It's your code, ultimately. But if you're shipping a package that other developers might use, or if any of your toolchain (from IDE, through static analysis, to documentation generation itself) aren't happy with the non-standard usage, then you'll have to weigh up the decision again. Either way it comes down to whether you're the only one (person or machine) reading your code; if you're not, then stick with the standards, even if it means typing a few extra characters.
--
* This can include things that actually do affect the way the code runs - PHP allows you to fetch these annotations with the getDocComment methods in the Reflection API. Use-cases for this tend not to include #param annotations (more often it'll be something package specific like Doctrine's ORM annotations), which are almost exclusively used for documentation, but I don't want to over-generalise and say that this can't have an effect on your code's actual functionality.
The phpDocumentor docs state that the Datatype field is required for #param. Those docs are quite old, but I would expect apps which consume tags to still abide by that requirement. Lately, I've tended to skip the #param tag completely when I have an explicit typehint present.
PHPCS will alert if you leave it out but have a typehint, like in your example:
/**
* #param $arg The arg.
*/
public function foo(int $arg) {
PHPStan will alert if you have a #param tag type and a typehint that don't match, like this:
/**
* #param string $arg The arg.
*/
public function foo(int $arg) {
Essentially, I seek to pass a static class method to a callback, but do not wish to do so using a hard-coded string, but rather the fully-qualified class method literal. We can do that using classes like so:
$name = NS\FooClass::class;
instead of:
$name = 'NS\FooClass';
which will give us the string of the fully-qualified name of the class. I seek to be able to do something similar for a class method like so:
$name = NS\FooClass::foo_method::method;
instead of:
$name = 'NS\FooClass::foo_method';
It is more manageable and I can use the IDE functionality way better using the literals. Any similar way I can achieve what I want with the class methods without using strings?
There is currently no such mechanism built into the language. It has been suggested - see for instance this discussion from Feb 2020 - but there are more nuances to think about than might be immediately apparent; notably:
Should the syntax resolve at run-time and check the existence of the class and the method (::class in most cases doesn't; a bare function like strlen::func would have to because of the way namespaces resolve; an object implementing __callStatic could never be used this way)?
Should the result be a string, an array (see below), or a Closure object?
Anyway, that's a topic for elsewhere...
As the manual page on the callable type says, there are two ways to specify a static method for use as a callback:
As a string, as in your example 'NS\FooClass::foo_method'
As an array where the first part is a class name, and the second part is a the method name: ['NS\FooClass', 'foo_method']
Since only the class name needs to be qualified with namespace information, you can use ::class with the second syntax to get nearly what you wanted:
$callback = [NS\FooClass::class, 'foo_method'];
This allows any decent IDE to spot the reference to the class, and allows you to reference it by an imported or aliased name.
It's worth noting that if the callable type is specified in a parameter or return type declaration or a docblock, some IDEs (e.g. PhpStorm) will "understand" either format as a reference to the method, and include it in features like "find usages" and "go to declaration".
How do I document class constants for phpDoc? I've read the manual but I can't find anything about them.
Constants only need a docblock that contains the description. No specific tag is necessary. The code parser itself identifies constants and displays them as such in the generated documentation (here's an example).
I'm fairly sure that you can use #const, though I can't find any English documentation. There's a German example here. It shows define statements rather than class constants, but IIRC the syntax is the same.
Nine years later, an edit...
It is clear now that the above is bad advice as #const has not appeared in the docs and it seems it will not.
Using #var seems to work, though I cannot see it explicitly specified anywhere.
The full list of all PHPDoc 3 tags: Tag reference
The manual says the following:
#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
Is there a proper way to document a constant defined using define()? #var doesn't really make sense. The only thing I can think of is to omit the tag, and just write the description in the PHPdoc comment.
phpDocumentor does not recognize or utilize a #const tag. phpDocumentor recognizes a constant when it sees the "define" keyword in the code. Its output templates will show all constants in the output documentation, listed as constants. The only thing needed in the constant's docblock is a description, although many other "standard" tags are allowed if you feel like you need them [1].
[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_elements.pkg.html#procedural.define
Use #const.
/**
* #const FOO Bar
*/
define('FOO', 'Bar');
Documentation (Sorry, the only docs I can find are in German.)
You actually want to use #type, see the Github PHP Documentation.
How do I document class constants for phpDoc? I've read the manual but I can't find anything about them.
Constants only need a docblock that contains the description. No specific tag is necessary. The code parser itself identifies constants and displays them as such in the generated documentation (here's an example).
I'm fairly sure that you can use #const, though I can't find any English documentation. There's a German example here. It shows define statements rather than class constants, but IIRC the syntax is the same.
Nine years later, an edit...
It is clear now that the above is bad advice as #const has not appeared in the docs and it seems it will not.
Using #var seems to work, though I cannot see it explicitly specified anywhere.
The full list of all PHPDoc 3 tags: Tag reference
The manual says the following:
#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