ARTIGOS

PHPDOX para gerar documentação automática em PHP

Como gerar documentação automaticamente a partir dos fontes de seu projeto

- Fonte: [http://phpdox.de/](http://phpdox.de/)
- Documentação: [http://phpdox.de/documentation.html](http://phpdox.de/documentation.html)

O `phpDox` é um gerador de documentação para projetos `PHP`. O foco principal da ferramenta está no enriquecimento da documentação gerada, adicionando detalhes como: composição do projeto, complexidade e muito mais.

## Requerimentos

A versão atual do `phpDox` é: `0.12` e para ela a versão necessária do `PHP` é 7.1 ou superior. Para usuários que usarem versões anteriores do `PHP` devem usar o `phpDox 0.11.2`.  Os demais requisitos serão instalados juntamente com  a ferramenta.

### Instalação

#### Instalação via Phar

O `phpDox` é disponibilizado com um instalador próprio, usando um arquivo `phar`, para tal você pode obter uma versão desse arquivo pelo endereço de lançamentos de versões:https://github.com/theseer/phpdox/releases/latest. Você deve usar o `phive` para executar a instalação.

```bash
$ phive install phpdox
```

Agora você pode executar o `phpDox` pela linha de comando.

```bash
$ tools/phpdox --version
```

Se a instalação foi concluída com sucesso você terá o seguinte retorno:

```bash
phpDox 0.12.0-dev - Copyright (C) 2010 - 2019 by Arne Blankerts and Contributors
```

#### Instalação via Composer

Para instalar usando o composer basta executar o seguinte comando:

```bash
$ composer require --dev theseer/phpdox 
```

Agora você pode executar o `phpDox` pela linha de comando.

```bash
$ vendor/bin/phpdox --version
```

Se a instalação foi concluída com sucesso você terá o seguinte retorno:

```bash
phpDox 0.12.0-dev - Copyright (C) 2010 - 2019 by Arne Blankerts and Contributors
```

## Comandos básicos

Para obter ajuda e aprender os comandos básicos do `phpDox` você deve executar essa linha em seu terminal:

```bash
$ vendor/bin/phpdox --help
```

Retorno:

```
phpDox 0.12.0-dev - Copyright (C) 2010 - 2019 by Arne Blankerts and Contributors

Usage: phpdox [switches]

-f, --file       Configuration file to use (defaults to ./phpdox.xml[.dist])

-h, --help       Prints this usage information
  -v, --version    Prints the version and exits

-c, --collector  Run only collector process
  -g, --generator  Run only generator process

--backends   Show a list of available backends and exit
      --engines    Show a list of available output engines and exit
      --enrichers  Show a list of available output enrichers and exit

--skel       Show an annotated skeleton config xml file and exit
      --strip      Strip comments from skeleton config xml when showing
```

### Configuração do `phpDox`

Para configurar o modo de execução, diretório do projeto, extensão de saída e todas as outras configurações, você precisa criar um arquivo chamado `phpdox.xml`, como esse arquivo espera tags específicas de configuração o  `phpDox` oferece um arquivo com um template completo das configurações, para gerá-lo use o seguinte comando:

```bash
$ vendor/bin/phpdox --skel > phpdox.xml
```

O arquivo criado terá todas as tags que podem ser usadas juntamente com algum comentário educativo. Outra opção é você usar o exemplo mínimo fornecido na documentação:

```xml
<?xml version="1.0" encoding="utf-8" ?>
<phpdox xmlns="http://xml.phpdox.net/config">
  <project name="Example" source="${basedir}/src" workdir="${basedir}/build/api/xml">
    <collector backend="parser" />
    <generator output="${basedir}/build/api">
      <build engine="html" output="html"/>
    </generator>
  </project>
</phpdox>
```
  
No arquivo de configuração mostrado acima, configuramos o seguinte:  
  
- "Example" é o nome do projeto
- O projeto está em `$ {basedir} / src`  
- O `workdir` (onde a representação XML do código-fonte está armazenada em cache) é` $ {basedir} / build / api / xml`  
- O gerador de saída é `html` e colocar o resultado no diretório` $ {basedir} / build / api / html`  
  
A variável `$ {basedir}` é resolvida para o diretório que contém o arquivo de configuração.

## Anotações

O `phpDox` não possuí uma lista especificando quais anotações (`todo`, `author`, etc) serão analisadas. Todas as anotações presentes no projetos são interpretadas pelo `phpDox`. No entanto, apenas algumas são exibidas nos templates `HTML`, as anotações visíveis são:

* Global
	* @todo
	* @fixme
	* @author
	* @copyright
	* @license
* Class, Interface, Trait
	* Nenhuma anotação específica	
* Propriedades, Constantes
	* @var
* Funções
	* @return
	* @throws
	* @param

## Enriquecedores

Enriquecedores ou *Enrichers* são usados para que as documentações sejam geradas com ainda mas informações. O `phpDox` disponibiliza sete enriquecedores:

**Build :** Enriquecedor padrão e sempre ativo,  gera dados sobre a geração da documentação (informações da plataforma, informações do `phpDox`)

**Git :** Adiciona o *branch* a partir da qual a documentação foi construída, também exibe o histórico do git em classes e interfaces.

Display the branch from which the documentation was build, also display git history on classes/interfaces/traits

**Checkstyle** e **PHPCS :** Em todas as classes, interfaces e *traits*, são exibidas listas com violações encontradas no relatório do phpcs.

**PHPMessDetector :** Em todas as classes, interfaces e *traits*, são exibidas listas com violações encontradas no relatório do phpmd.

**PHPUnit** Em todas as classes, será exibido um resumo com os testes bem sucedidos e os que falharam.

**PHPLoc :** Na página inicial, são exibas estatísticas geradas a partir do `PHPLoc`.

## Engines

Engines são os métodos usados para analisar o projeto e transformar essas informações e documentação. O `phpDox` tem duas *engines*:

-   HTML
-   XML

## Como usar

Com o arquivo `phpdox.xml` configurado, o desenvolvedor só precisa executar uma linha de comando para gerar a documentação de um projeto:

```bash
$ vendor/bin/phpdox -f phpdox.xml
```

> Informações da engine usada, localização do projeto entre outros devem ser configuradas no arquivo phpdox.xml.

Você pode verificar demonstrações do uso da ferramente em: [http://phpdox.de/demo/PHPUnit/index.xhtml](http://phpdox.de/demo/PHPUnit/index.xhtml).

ARTIGOS

PHPDOX para gerar documentação automática em PHP

Como gerar documentação automaticamente a partir dos fontes de seu projeto

COMENTE SOBRE