Exportação do JSDoc

Introdução

No processo Exportar JSDoc3 é possível gerar a documentação JSDoc da API do Bematech ERP em um diretório do sistema operacional ou da VFS (Virtual File System), podendo também simular a exportação para analisar possíveis erros nos arquivos de forma individual. Pode-se especificar o diretório de saída da exportação e o template utilizado na geração da documentação.

Objetivo

Utilizar o processo Exportar JSDoc3, localizado em Desenvolvimento > Documentação, para gerar documentação JSDoc a partir de um diretório do sistema operacional ou da VFS.

Estrutura do guia

• • Fluxo Operacional

    • • Gerando a Documentação

      • Definindo a configuração JSDoc

      • Testando exportação dos arquivos

      • Exportar documentação

Pré-requisitos

Para executar o processo Exportar JSDoc3 é necessário ter o JSDoc3 instalado. Também é necessário ter o Node.js instalado.

Instalando o Node.js: entre no site http://nodejs.org/ e clique em escolha a opção adequada para o seu sistema operacional.

Instalando o JSDoc3: execute o seguinte comando npm install -g jsdoc

Fluxo operacional

Extraindo a documentação

Para extrair a documentação JSDoc dos códigos-fontes deve ser utilizado o processo Exportar JSDoc3 localizado em: Bematech > Desenvolvimento > Documentação.

Ao abrir esse processo será exibida uma grade de configurações, onde encontram-se os seguintes campos:

• • Tipo: seleciona o tipo de exportação (diretório do sistema operacional ou VFS).

  • Caminho: diretório de saída da exportação, no caso do tipo escolhido ser diretório do sistema operacional, o diretório deverá estar vazio.

  • Caminho do template: indica onde se encontra o template que deseja-se utilizar, caso não seja preenchido, o template padrão do jsdoc será utilizado.

  • Versão: informa a versão do jsdoc instalada e verifica se ela é compatível com o processo.

Após informar as configurações desejadas, clique em Preparar para avançar para a interface de seleção dos arquivos que serão exportados. Por padrão, todos os arquivos estarão selecionados, mas o usuário poderá mudar a seleção. Sempre selecione todos os arquivos caso esteja atualizando o diretório de documentação da VFS público, caso contrário a documentação pública não exibirá o JSDoc de todos os códigos. Após selecionar os arquivos, clique em Extrair Documentação para começar a extração da documentação, isso levará alguns minutos. Ao final, se concluído com sucesso, a documentação estará no diretório de saída informado na tela anterior, no campo "Caminho" da grade "configurações".

Testando exportação dos arquivos

Na grade com a interface de seleção dos arquivos se encontra o botão Testar exportação que permite uma simulação da exportação de cada arquivo, detectando possíveis problemas referentes a exportação sem ter que gerar a documentação completa.

Exportando códigos-fonte para um repositório Git

Alternativamente à exportação direta realizada pelo processo, é possível exportar também os arquivos fontes para um repositório Git e automatizar a geração do JSDoc por meio de ferramentas de integração contínua, como o Jenkins. Para isso, utilize o processo Exportar arquivos com JSDoc para repositório Git para criar uma URL que pode ser executada periodicamente para sincronizar os arquivos fontes de uma base de dados para um repositório Git. Uma vez exportado os arquivos fontes, o JSDoc pode ser executado diretamente sobre este repositório, seguindo as orientações da ferramenta em http://usejsdoc.org/.