What are strings started with @ within PHP comments?

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 does this string represent and what is its relationship to external files, functions, etc.?

    
asked by anonymous 06.03.2017 / 18:27

5 answers

4

As user @bfavaretto already replied in comments, the @ symbol is used as a policy for documentation software.

Let's look at phpDocumentor . This software will read your code and generate documentation automatically. But how does he know who is the author of a function?

Enter annotations with @ . When you say @author MagicHat you are telling the documentation software that this method was written by author MagicHat.

In the same way there are several other tags to annotate the code.

In php itself, this is all just a comment and will be totally ignored.

Caution : Some software literally uses comments to make decisions. The Doctrine library has the option to read this type of comment and understand the relationship of the objects to the database. If you're not using a library of this type, do not worry, there's nothing to fear.

Edit : These comments that begin with @ are called Annotations. They are used in several PHP libraries, such as Doctrine , Symfony Validator , etc.

    
06.03.2017 / 18:37
3

This is nothing more than a documentation of the code, it only serves as information. For example: What is expected as a parameter, what class or method returns, and so on.

View the phpDocumentor documentation

    
06.03.2017 / 18:33
3

Summary :

Strings started with the @ sign are called tags . A tag preceded by @ forms a annotation . In this way it provides brief and uniform meta-information about the associated element.

    
06.03.2017 / 18:40
2

Strings started with @ in comments in PHP serve to standardize documentation.

The standardization proposed by the group PHP-FIG for documentation is currently in DRAFT which means "a status of recommendation" defined in PSR-5 PHPDoc Standart .

They are used to describe the code, report copyright, declare inputs and outputs of functions as well as code strings clearly understood by the entire PHP developer community regardless of language and source.

They should (if you use) precede the code, function or string they reference.

    
06.03.2017 / 18:47
1

They are tags that identify certain information within a documentation block or DocComment, introducing a context to the data and help self-documenting tools to separate the information.

In PHP for example, we can use the phpDocumentor tool, which will generate a document with all comments of classes, functions and variables added to the source code.

A list of tags (with description) can be found in the phpDocumentor documentation: link

In the text you provided, this block is presenting the PHPMailer package, created by Andy Prevost, Marcus Bointon and Jim Jagielski, copyrights being held by Jim Jagielski from 2010 to 2012 and kept with Andy Prevost from 2004 to 2009 , at the end the license type of this package is informed.

Tags and documentation do not influence anything in the code and can be deleted, its usefulness is only to allow understanding of that code snippet.

If you use some IDE to develop code, the documentation blocks will be displayed when using classes, methods, and variables by the system.

    
06.03.2017 / 18:49