6
I was reading a code, like this :
/**
* PHPMailer - PHP email creation and transport class
* NOTE: Requires PHP version 5 or later
* @package PHPMailer
* @author Andy Prevost
* @author Marcus Bointon
* @author Jim Jagielski
* @copyright 2010 - 2012 Jim Jagielski
* @copyright 2004 - 2009 Andy Prevost
* @license Public License
*/
What represents this string and how it relates to external files, functions, etc?
4
As the user @bfavaretto has already responded in the comments, the symbol of @ is used as a directive for documentation software.
Let’s see the phpDocumentor. This software will read your code and generate a documentation automatically. But how does it know who is the author of a function?
Enter the notes there with @. When you say @author MagicHat you are telling the documentation software that this method was written by the author Magichat.
Similarly there are several other tags to annotate the code.
In php itself, this is all just a comment and will be totally ignored.
Care: Some software literally uses comments to make decisions. The library Doctrine has the option to read this type of comment and understand the relationship of the objects with the database. If you are not using a library of this type, don’t worry, there is nothing to fear.
Edit: These comments that begin with @ are called Annotations. They are used in various PHP libraries, such as Doctrine, Symfony Validator, etc..
3
This is nothing more than documentation of the code, only serves as information. For example: What is expected as parameter, what class or method returns and etc.
Thank you for your attention, this value can be used externally, or what its relation to the outside world to the comments ?
In the specific case of phpDocumentor, there is a web interface where you can see all the information of your code in a well organized way, but other than that there is no external utility as far as I know.
3
Summary:
Strings started with the sign @ are called tags. One tagpreceded by the @forms a annotation. This way it provides meta-information in a succinct and uniform way about the associated element.
2
The strings started with @ in comments on PHP are used to standardize documentation.
The standardization proposed by the group PHP-FIG for documentation currently on DRAFT which means "a state of recommendation" as defined in PSR-5 Phpdoc Standart.
They are used to describe code, inform copyright, declare inputs and outputs of functions as well as strings of code clearly understood by the entire developer community PHP independent of language and origin.
Must (if used) precede the code, function or string to which they refer.
1
Tags that identify certain information within a documentation block or Doccomment, introducing a context to the data, and help self documentation tools separate the information.
In PHP for example, we can use the phpDocumentor tool, which will generate a document with all class, function and variable comments added to the source code.
A list of tags (with description) can be found in the phpDocumentor documentation: https://www.phpdoc.org/docs/latest/references/phpdoc/tags/index.html
In the text you provided, this block is featuring the Phpmailer package, created by Andy Prevost, Marcus Bointon and Jim Jagielski, with the copyrights being held by Jim Jagielski from 2010 to 2012 and held by Andy Prevost from 2004 to 2009, at the end is informed the license type of this package.
The tags and documentation do not influence anything in the code and can be deleted, its usefulness is only to allow the understanding of that piece of code.
If you use an IDE to develop code, the documentation blocks will be displayed when using classes, methods and variables by the system.
Browser other questions tagged php
You are not signed in. Login or sign up in order to post.
https://www.phpdoc.org/, https://www.phpdoc.org/docs/latest/index.html
– bfavaretto
Related: Phpdoc - What is, what is useful and how to use?
– rray
That’s right dup right there... @rray
– MagicHat
@Magichat, your question seems to be duplicated, but her scope is much larger. The indicated question explicitly speaks of documentation, while your question questions the general scope of annotations, which can be used for more purposes, such as data validation and ORM integration. See my answer to better understand.
– jlHertel