7

Estava lendo um código, assim :

/**
 * 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
 */

O que representa essa string e qual a relação dela com os arquivos, funções, etc, externos?

4
  • 3
    phpdoc.org, phpdoc.org/docs/latest/index.html
    – bfavaretto
    Commented 6/03/2017 às 17:29
  • 2
    Relacionada: PHPDoc - O que é, qual sua utilidade e como usar?
    – rray
    Commented 6/03/2017 às 17:35
  • Tá bem dup dessa ai mesmo... @rray
    – MagicHat
    Commented 6/03/2017 às 17:39
  • @MagicHat, Sua pergunta parece ser duplicada, mas o escopo dela é bem maior. A pergunta indicada fala explicitamente de documentação, enquanto a sua pergunta questiona o escopo geral de anotações, que podem ser utilizadas para mais finalidades, como validação de dados e integração com ORM. Veja a minha resposta para entender melhor.
    – jlHertel
    Commented 6/03/2017 às 17:41

5 Respostas 5

4

Como o usuário @bfavaretto já respondeu nos comentários, o simbolo de @ é utilizado como uma diretiva aos softwares de documentação.

Vejamos o phpDocumentor. Este software vai ler o seu código e gerar uma documentação automaticamente. Mas como ele sabe quem é o autor de uma função?

Entram ai as anotações com @. Quando você diz @author MagicHat você está dizendo ao software de documentação que este método foi escrito pelo autor MagicHat.

Desta mesma forma existem diversas outras tags para anotar o código.

No php em si, isto tudo não passa de um comentário e será totalmente ignorado.

Cuidado: Alguns softwares utilizam literalmente os comentários para tomar decisões. A biblioteca Doctrine tem a opção de ler este tipo de comentário e entender a relação dos objetos com o banco de dados. Se você não está utilizando uma biblioteca deste tipo, não se preocupe, não há nada a temer.

Edit: Estes comentário que iniciam com @ são chamados de Annotations. São usados em varias bibliotecas PHP, como Doctrine, Symfony Validator, etc.

3

Isso nada mais é que uma documentação do código, só serve como informação. Por exemplo: O que é esperado como parâmetro, o que a classe ou método retorna e etc.

Veja a documentação do phpDocumentor

2
  • Obrigado pela atenção, esse valor pode ser usado externamente, ou qual a relação dele com o mundo externo aos comentários ?
    – MagicHat
    Commented 6/03/2017 às 17:35
  • No caso especifico do phpDocumentor, há uma web interface onde você pode ver todas as informações do seu código de uma forma bem organizada, mas tirando isso não há utilidade externa até onde eu sei.
    – KillerJack
    Commented 6/03/2017 às 17:39
3

Resumo:

As strings iniciadas com o sinal @ são chamadas de tags. Uma tagprecedida do @forma uma annotation. Dessa forma provém meta-informações de maneira sucinta e uniforme sobre o elemento associado.

2

As strings iniciadas com @ em comentários no PHP servem para padronizar a documentação.

A padronização proposta pelo grupo PHP-FIG para documentação atualmente esta em DRAFT o que significa "um estado de recomendação" definido no PSR-5 PHPDoc Standart.

São utilizadas para descrever o código, informar copyright, declarar entradas e saídas de funções bem como strings do código de forma clara entendida por toda a comunidade de desenvolvedores PHP independente de idioma e origem.

Devem (caso sejam utilizas) preceder o código, a função ou a string a qual fazem referencia.

1

São tags que identificam determinadas informações dentro de um bloco de documentação ou DocComment, introduzindo um contexto ao dado e auxiliam ferramentas de auto-documentação a separarem as informações.

No PHP por exemplo, podemos utilizar a ferramenta phpDocumentor, que irá gerar um documento com todos comentários de classes, funções e variáveis adicionadas ao código-fonte.

Uma lista de tags (com descrição) pode ser consultada na documentação do phpDocumentor: https://www.phpdoc.org/docs/latest/references/phpdoc/tags/index.html

No texto que você forneceu, este bloco está apresentando o pacote PHPMailer, criado por Andy Prevost, Marcus Bointon e Jim Jagielski, sendo os direitos de cópia mantidos a Jim Jagielski de 2010 à 2012 e mantidos à Andy Prevost de 2004 à 2009, no final é informado o tipo de licença deste pacote.

As tags e documentação não influenciam em nada no código e podem ser apagadas, sua utilidade é apenas permitir a compreensão daquele trecho de código.

Se você utiliza alguma IDE para desenvolver códigos, os blocos de documentação serão exibidos ao utilizar classes, métodos e variáveis pelo sistema.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .