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.
Related
Wherever I go I see documentation for php with the following:
/*
* stuff
* stuff 2
*/
My question is can I get away with just:
/*
Stuff 1
Stuff 2
*/
Or is that for some reason counter indicated thanks?
Usually when you see coding habits following a particular pattern it is down to one of the following reasons:
Syntax denotes it
Coding style requests it
Programmatic parsing is enhanced by it.
With comments it is generally the latter two.
There are a number of coding styles for the /**/ comment block, across numerous languages (not just PHP). Coding styles generally are just personal/team preference, usually with some real arguments as to why a particular habit is preferred. Most often, readability is king.
The most common of these particular comment-styles would be what is referred to as a DocComment or DocBlock.
http://docs.phpdoc.org/guides/docblocks.html
This is a way of programatically powering the generation of your documentation directly from comments. Because the comments are parsed by code, it is specified with a particular pattern (note the /** prefix), making things easier to detect and reformat:
/**
* This is my DocBlock
*
* Each new line is prefix with a *
* and any special attributes are
* prefixed with an #something
*/
You by no means have to do this though, and a simple /* and */ will suffice for multiline comments. On the projects that I have worked on in the past, the difference between using a * on every line and not makes it clear when a comment is a real comment, against when it is just being used to comment out a portion of code.
The format you're describing is called PHPDoc. It's often used to document classes and methods (IDEs can make use of PHPDoc). This comment format is sometimes required to store annotations for various frameworks and libraries (e.g. Symfony uses it on controllers for routing.)
If you're not using annotations or documenting classes/functions, then there's no reason to write in the PHPDoc convention.
PHPDoc:
http://www.phptherightway.com/#phpdoc
Symfony annotation example (see the #Route examples):
https://symfony.com/doc/current/controller.html
Simply put, yes you can!
When creating .php files, the developer will often insert comments, as to add explanations for their coding.
There are two ways of adding comments. They are as follows:
/*[Comment Here]*/ This allows the Developer to add comments, which spread over multiple lines. For example:
/*
[This is a Comment]
[This is also a Comment]
*/
You just need to ensure that your Comment falls within the /**/ and that these are enclosed within the <?php [Code Data] ?> tags.
Alternatively, you can use '//'. Unlike the above, this will only allow you to insert a Comment on one line. If you were to go into the next line, you would need to add an additional //. Just like the above, you need to also ensure these // are placed within the <php? [Code Data] > tags.
As for the list of '*', I believe this is just for presentational and organisational purposes. They certainly do not affect the Comment itself.
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
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.
How can I mark up constants using PHPDoc? What #-tag should I use? I've thought of #var, but that's not appropriate.
The short answer is that there isn't one. And there doesn't need to be one either. The documentation generator is smart enough to be able to see the constant declaration. So just put the summary there without any #-tags. That should be all that you need to do...
class foo {
/**
* This constant does something that you need.
*/
const FOO = 'bar';
}
For constants, you use #type.
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