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.
Related
I'm on my way to upgrade my projects to PHP 8.0+. Until now, in the code comments, I used the #param and #return tags like in "option 1", instead of like in "option 2":
Option 1:
#param string[] ....
#return User[] ....
Option 2:
#param array ....
#return array ....
Though, because I don't know if the first form is officially allowed, I begin to ask myself, if it wouldn't be better to switch to the second option... So, I'd like to ask you: Is there any official PHPDoc reference for documenting PHP codes available?
Also, is it at all advisable to use the first option instead of the second one? In other words: are there any arguments speaking against it - having the future in mind too?
Thank you for your time.
P.S: I found the reference of PHPDocumentor, but I have the feeling, that it is not the official PHP one and not (yet) compatible with PHP 8.0+.
PHPDoc isn't a part of the official documentation but since it has been so widely adapted I highly doubt it will be ignored.
PHP itself prior to version 8 defines only comment syntax https://www.php.net/manual/en/language.basic-syntax.comments.php which does not include any # related elements.
Version 8 of PHP introduces attributes https://www.php.net/manual/en/language.attributes.overview.php which will be the native replacement for annotations.
For example https://api-platform.com/docs/core/filters/
PHP till 7.x
/**
* #ApiResource(attributes={"filters"={"offer.date_filter"}})
*/
class Offer
{
// ...
}
Since PHP 8
#[ApiResource(attributes: ['filters' => ['offer.date_filter']])]
class Offer
{
// ...
}
PSR Standard
PHP FIG defined 2 PSR standards ( Not approved yet )
PSR-5 https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md
PSR-19 https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md
Though, because I don't know if the first form is officially allowed,
I begin to ask myself, if it wouldn't be better to switch to the
second option...
I will just stick with the Option 1. It is extremely beneficial for code completion standpoint.
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) {
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.
I have objects with many variables that I declare and explain in the comments. I am commenting very thoroughly for later processing using phpDoc, however I have no experience with actually compiling the documentation yet.
I find it very annoying that with phpDoc notation, each variable eats up four to six lines of code even if the only attribute I want to set is the description:
/**
* #desc this is the description
*/
var $variable = null;
I would like to use the following notation:
# #desc this is the description
var $variable = null;
is there a simple way to tweak phpDoc into accepting this, or will it give me trouble when I actually try to compile documentation out of it? I don't need the tweak now (although it's appreciated of course), just a statement from somebody who knows phpDoc whether this is feasible without having to re-engineer large parts of its code.
Just write one-line docblocks
/** #desc this is the description */
var $variable = null;
Problem solved.
In addition to what Frank Farmer mentioned (+1 to his solution),
/** is declared as T_DOC_COMMENT in the PHP tokenizer since PHP 5. This means to say that documentation notation are all parsed from /** to */.
You can't just use # or /* to write your PHP documentations.
See:
http://www.php.net/manual/en/tokens.php