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.
Related
I'd like to organize my constants neatly.
In C++ I would've put enums or variables in a namespace (or more) like so:
namespace foo
{
namespace bar
{
enum herp { derp, sherp, sheep };
}
namespace Family
{
const string mom = "Anita";
const string son = "Bob";
const string daughter = "Alice";
}
}
This would give me the possibility to access them like
int x = foo::bar::derp;
string nameOfMom = foo::Family::mom;
string nameOfSon = foo::Family::son;
How can I implement this in PHP?
As far as the enum is concerned: There is no enum in PHP. You can write an array (which is in fact a HashTable underneath) or you'll have to use a (separate) namespace and/or define a class for that, given that an enum is closer to a class, I'd probably opt for the latter and go ahead and write:
class FakeEnum
{
const DERP = 0;
const SHERP = 1;
const SHEEP = 2;
}
jycr753 already linked this question, and it does show how you could emulate enums in PHP, but if you ask me, that's just taking it that little bit too far. Using a ReflectionClass just to emulate a missing construct is like modifying your car so it can double as a motorcycle.
On to the namespaces:
Namespaces in PHP are relatively "new", and they are not 100% equivalent to C++ namespaces. For one, they can't be nested in the way you are trying. For that, you'll have to resort to declaring classes inside a given namespace, and accept that only allows for 1 additional level.
All things asside, I take it you're looking for something like this:
namespace Foo
{
const FOOBAR = 123;
}
namespace Bar
{
const FOOBAR = 456;
}
namespace Work
{
const FOOBAR = __NAMESPACE__;
include 'global_const.php';
echo 'Global FOOBAR const is: ', \FOOBAR, PHP_EOL,
'Foo::FOOBAR is: ', \Foo\FOOBAR, PHP_EOL,
'Bar::FOOBAR is: ', \Bar\FOOBAR, PHP_EOL,
'Work::FOOBAR is: ', FOOBAR, PHP_EOL;
}
Where the global_const.php file defines a global constant like so:
define('FOOBAR', 'global');//just to be consistent ;-P
The resulting output is:
Global FOOBAR const is: global
Foo::FOOBAR is: 123
Bar::FOOBAR is: 456
Work::FOOBAR is: Work
Of course, in reality, your code will be spread-out over multiple files, and more often than not, you'll only use a single namespace for that file, and use other namespaces (≃ using in C++):
namespace My\Core\Components\Output;
use Foo,
Bar,
My\Core\Components\Input as CoreInput;
use External\Component\Input as HelperInput;
The inconsistencies in the PHP namespacing system are well documented (google search them). But to give you an example, if I start my file with the statements above, the following statement:
$myVar = Foo\SOME_CONSTANT;
resolves to
global namespace (\ for short)
->Foo namespace
-> SOME_CONSTANT
But if I were to remove the use Foo, the same statement resolves to:
\
-> My
-> Core
-> Components
-> Output
-> Foo
-> SOME_CONSTANT
Now that may seem perfectly reasonable, but the same rule does not apply to the core functions: \str_replace or str_replace are both resolved correctly, the only difference is that the latter will first perform a lookup for a function called str_replace in the current namespace, to then fall-back to the global namespace.
Ok, with some "goodwill" you could argue that this, too, is fairly predictable behaviour. Sadly, strangely or maliciously, PHP does not behave in the same way when using its core objects (like DateTime, stdClass, Exception or PDO...).
Take the mysqli_* extension, for example: you can use its procedural API throughout all of your namespaces and be a happy camper, but if you prefer the OO API, you'll have to use the use statements, or add a backslash whenever you write new \mysqli().
Ok, so PHP has its faults, but of course, we all know that much, as for your question, I believe I you have an answer now, and for me to continue this rant would be utterly pointless. Everything you need to know about namespaces can be found in the manual, BTW
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
I have a class in which I want to define some constants used by other classes. The const keyword isn't enough for me because I want for example to use a mathematical expression like 2.0 * pi() as a constant. How is done?
I understand you want to assign a mathematical expression to a constant.
Like:
const FOO = 2.0*pi();
PHP constants can only contain scalar values. If you want other classes to use shared information, you will have to use static functions/methods for this.
Example:
static public function foo()
{
return 2.0*pi();
}
Actually something similar is implemented in PHP 5.6 where you can assign results of various expressions to class constants.
You can read more about it here:
http://php.net/manual/en/migration56.new-features.php#migration56.new-features.const-scalar-exprs
and here:
https://wiki.php.net/rfc/const_scalar_exprs
Assigning results of functions is still not allowed according to the documentation, however the following expression that has the same result as your example should be completely valid:
const FOO = M_PI*2;
Be advised that PHP 5.6 does not have a stable release yet, so it is not recommended for now to use it in production.
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