fgldocumenter - Manual técnico

Introdução

Este manual apresenta a ferramenta fgldocumenter sob o ponto de vista da sua implementação, apresentando por isso:

Arquitectura

Estrutura funcional

Estrutura modular

Dependências

Arquitectura

O diagrama que se segue descreve a arquitectura usada pelo documentador.

Em termos conceptuais pode-se dividir nas seguintes componentes:

Repositório

Documentador

Parser/Extractor de documentação dos sources 4gl

Exportador para sources 4gl

Importador CSV

Exportador CSV

Gerador de HTML

Navegador

Repositório

O repositório é o local onde a informação sobre os programas está armazenada.

A ferramenta interage com esta informação importando para ele de várias formas e com origem em várias fontes. Fornece tambem a exportação, para vários formatos. É possivel um acesso on-line através de interface próprio (em ambiente Web) ou por SQL.

Documentador

O documentador é composto por vários módulos programados com linguagens e ferammentas distintas.

Tentou-se, ao máximo tentar garantir a autonomia de cada um, no entanto este objectivo não está ainda completamente atingido.

Existe um programa em perl que serve de interface com o utilizador para a execução das diferentes acções permitidas.

Permite a sua execução em ambientes gráficos ou por linha de comando sem qualquer interacção com o utilizador (para além de gerar mensagens).

Implementou-se, tambem um conjunto de métodos utilitários que disponibilizam serviços a cada uma das componentes, como por exemplo gestão de erros e escrita em ficheiros de log. Esta é talvez a razão das dependências dado que ainda não se atingiu um nivel de dependência nulo.

Parser / Extractor de documentação de sources 4gl

Recebendo o nome de um fonte de 4gl como parâmetro, efectua a sua análise sintática, carregando a informação em memória e posteriormente guardando-a depois (se escolhida a opção correspondente) num repositório relacional (dentro de uma base de dados).

Quando instalado corresponde a um executável.

Foi construido com as seguintes ferramentas:

Bison / Yacc

Flex / Lex

C

ESQL/C

Pode ser executado com as seguintes opções:

Usage: p4gl [-h] [-d] [-i] [-v] [-w level] -f ficheiro.4gl

   -h : Display this help message

   -d : Debug mode

   -i : Insert in the repository

   -v : Verbose mode

   -w : Warning level (1..10)

   -c : Generate documentation

   -s : Use standard comments for documentation

   -p package : Nome do package

Acesso ao repositório

O acesso ao repositório (para leitura e escrita) está construido em ESQL/C, como tal apenas pode aceder a repositórios em bases de dados Informix.

Penso que a configuração da base de dados onde o repositório estará instalado será efectuada usando a variável de ambiente DATABASE, mas isto tem de ser devidamente confirmado.

Exportador para sources 4gl

Desenvolvido em perl sob a forma de classe/objecto, lê a informação do repositório, para um ou mais módulos pretendidos, gera os comentários em formato fgldoc e insere-os dentro dos fontes de 4gl.

Importador CSV

Construido sob a forma de Classe / Objecto de perl trata de abrir o ficheiro para o qual foi configurado e carregar a informação que nele vem registada para uma tabela exactamente com o mesmo formato. Posteriormente e se pretendido efectua a normalização daquela informação para as tabelas normalizadas do repositório.

De notar que a informação carregada directamente no formato do ficheiro para pouco serve.

Exportador CSV

Efectua uma leitura da informação das tabelas em formato relacional devidamente normalizado, desnormaliza-a para a tabela p4gl_excel e efectua um unload dessa informação com um caracter separador.

Gerador HTML

Para que se possa usar esta informação em ambientes desconnectados, é possivel gerar uma réplica da informação disponivel no repositório para um directório a definir, em formato html.

Esta informação se alterada não pode depois ser carregada novamente e perde-se o acesso por SQL.

Esta abordagem é, no entanto a mais tradicional e usada por sistemas de documentação similares como por exemplo o Doxygen ou javadoc.

Navegador

Construido em JSP(s) permite o accesso on-line à informação disponivel sobre os programas residente no repositório.

Efectua o acesso através de JDBC.

Para alem dos JSP(s) que são compilados dinâmicamente pelo respectivo container contem algumas classes que deverão ser devidamente compiladas e instaladas no local correcto do servidor.

Modelo de dados do repositório

O repositório do documentador tem uma estrutura relacional pura, com integridade referencial.

Constitui o núcleo central de armazenamento da ferramenta, sem a qual nada consegue funcionar convenientemente.

Está, para já implementado e testado sobre um SGBD Informix.

Dada a normalização da estrutura (e o facto de não usar serials nem rowid(s)), não deverá ser demasiado complicado a conversão por forma a trabalhar noutros SGBD(s), nomeadamente o Postgresql.

p4gl_package

Identifica um package que tipicamente corresponde a uma directoria.

Coluna	Descrição
id_package
comments

p4gl_program

Programa executável para ser compilado.
Não suporta programas com o mesmo nome.
Obtido com um count distinct a source4gl.

Coluna	Descrição
program_name
comments

p4gl_module

Identifica um módulo 4gl (ficheiro 4gl compilável).

Coluna	Descrição
id_package
module_name
comments

p4gl_module_prog

Definição de dependências de sources (4gl) para a construção de um programa.

Coluna	Descrição
program_name
id_package
module_name

p4gl_function

Identifica uma função 4gl.

Coluna	Descrição
id_package
module_name
function_name
function_type
comments

p4gl_process

Identifica um processo analisado e desenhado que o software implementa.

Coluna	Descrição
id_package
den_process
comments

p4gl_process

Associa funções a processos.

Coluna	Descrição
id_package
module_name
function_name
id_process

p4gl_fun_parameter

Associa parametros a funções

Coluna	Descrição
id_package
module_name
function_name
item_num
var_name
data_type
comments

p4gl_fun_return

Valores de retorno de uma função.

Coluna	Descrição
id_package
module_name
function_name
item_num
var_name
data_type
comments

p4gl_fun_todo

Tarefas a executar de uma função.

Coluna	Descrição
id_package
module_name
function_name
item_num
comments

p4gl_table_usage

Utilizações de tabelas.

Coluna	Descrição
id_package
module_name
function_name
table_name
operation	'I' ,'U' ,'D' ,'S'

p4gl_excel

Dados desnormalizados carregados directamente de uma folha de cálculo.

Coluna	Descrição
module_name
id_process
function_name
parameters
returns
called
comments

Dependências

Para ser compilado e(ou) executado correctamente, o documentador tem de cumprir um certo número de requisitos, que de seguida se descrevem.

Run-time

Perl >= 5.6

Perl DBI

Perl DBD::Informix

Perl::Tk

Perl::Data

Perl::Getopt

Informix CLI

JSP

Jakarta Tomcat

JRE

Informix JDBC

Compilação

Informix ESQL/C

Bison

Lex

Gcc

J2SE SDK

Make

Ficheiro com dados de configuração

O ficheiro de configuração tem o formato de um export de dados de perl usando o módulo Data::Dumper.

Pode ser modificado manualmente, no entanto terá de se ter cuidado para garantir que cada linha consegue ser correctamente avaliada pela instrução eval do perl.