7/24/2019 Documentando c
1/31
GERADOR DE DOCUMENTAGERADOR DE DOCUMENTAOO
PARA LINGUAGEM C,PARA LINGUAGEM C,UTILIZANDO TEMPLATESUTILIZANDO TEMPLATES
Acadmico: Vilmar Orsi
Orientadora: Joyce Martins
7/24/2019 Documentando c
2/31
Roteiro
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Roteiro
Introduo
Objetivos do trabalho
Fundamentao terica
Desenvolvimento do trabalho
Concluso
Extenses
7/24/2019 Documentando c
3/31
Introduo
Importncia da documentao Evoluo na indstria de software Manuteno e adaptao de software
Qualidade da documentao Atualizao (periodicidade) Reflexo da realidade do software
Soluo Combinar cdigo fonte e documentao
Facilitar acesso documentao gerada
Escolha da linguagem C
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Introduo
7/24/2019 Documentando c
4/31
Objetivos do trabalho
Desenvolver uma ferramenta para a gerao automtica de documentaopara programas escritos em C.
Disponibilizar analisadores Lxico Sinttico Semntico
Definir um conjunto de marcadores especiais Tags DocComments
Gerar a documentao
HTML
Utilizar templates Para formatao da documentao
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Objetivos do trabalho
7/24/2019 Documentando c
5/31
Fundamentao terica
Conceitos bsicos Documentao de software
Geradores de cdigo e de documentao Analisadores de linguagens de programao Motores de templates
Trabalhos correlatos Javadoc Gerador de documentao do C# CDoc
Doxygen
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Fundamentao terica
7/24/2019 Documentando c
6/31
Documentao de software
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Fundamentao terica Conceitos Bsicos Documentao de software
Associada a qualidade do software (Pfleeger)
Gerao de forma in-line(Pfleeger)
Cdigo fonte Economia de custo e tempo
Geralmente no realizada por: No ser vital para o software
Prazos e verbas insuficientes Falta de poltica organizacional
7/24/2019 Documentando c
7/31
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Fundamentao terica Conceitos Bsicos Geradores de cdigo e de documentao
Geradores de cdigo e de documentao
Geradores so programas para escrever programas (Herrington)
Os geradores de cdigo podem ser classificados em Expansores de cdigo
Geradores mistos Geradores parciais de classes Geradores de camadas de aplicao Formatadores de cdigo
Geradores de documentao
templates
cdigo fonte
gerador dedocumentao
documentao
7/24/2019 Documentando c
8/31
Analisadores de linguagens de programao
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Fundamentao terica Conceitos Bsicos Analisadores de linguagens de programao
Compiladores Linguagem-fonte (alto nvel) Linguagem-alvo (cdigo de mquina)
rvore sinttica
obter prximotoken
token
programa
fonte
analisador lxico
tabela de smbolosanalisador sinttico
analisador semntico
7/24/2019 Documentando c
9/31
Motores de templates
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Fundamentao terica Conceitos Bsicos Motores de templates
Templatespodem conter cdigo esttico e dinmico
Permitem a separao do cdigo dinmico e do cdigo de interface
Cada motor de templatesdefine uma linguagem atravs da qual os templatesdevero ser escritos
FastTrac
Velocity
Associam o templatecom as informaes contidas em uma estrutura de dados
#para-cada (@include)
#se(@comentrio.possui(@autor))
Autor: @comentrio.autor#fecha
#fecha
Esttico/ Dinmico
7/24/2019 Documentando c
10/31
Desenvolvimento do trabalho
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Desenvolvimento do Trabalho
Levantamento dos requisitos
Anlise e identificao das informaes necessrias para gerar a documentao
Especificao das estruturas de dados para o armazenamento das informaes
Adaptao da gramtica C ANSI
Especificao de uma linguagem de DocComments
Especificao de uma linguagem de templates
Especificao da ferramenta atravs dos diagramas UML de casos de uso eclasses
Implementao da ferramenta
7/24/2019 Documentando c
11/31
Requisitos da ferramenta
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Requisitos da ferramenta
Requisitos funcionais
Gerar documentao, no formato HTML
Realizar anlises lxica e sinttica do cdigo fonte
Permitir o uso de tags HTML Usar templatespara a modelagem do documento a ser gerado
Disponibilizar uma interface para permitir a elaborao dos templates
Disponibilizar uma interface para a insero de comentrios no cdigo
fonte Disponibilizar um conjunto tags
Requisitos no-funcionais Utilizar marcadores especiais no estilo dos marcadores definidos no JavaDoc
Ser implementado utilizando o ambiente Delphi 7.0
Ser compatvel com o sistema operacional Windows 98, 2000 e XP
7/24/2019 Documentando c
12/31
Identificao das informaes para a documentao
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Identificao das informaes para a documentao
Diretivas
Declaraes Enumeradores (enum) Estruturas (struct e union) Definies de tipos (typedef) Funes Variveis
Documentao Arquivos Projetos (.PJT)
/*@
@cabealho:
@autor: Vilmar Orsi@motivao: Desenvolver uma ferramenta para desenhos
*/
#include "desenho.c"
#include "uestrutura.c"
#include "uestrutura.h"
7/24/2019 Documentando c
13/31
Especificao das estruturas de dados
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao das estruturas de dados
TComment
- algoritmo: string- autor: String- data: string- descontinuado: String- descricao: string- desde: String- entrada: string- fonte: String
- li nk: string- motivacao: String- orientacao: string- parametro: String- retorno: string- saida: String- versao: string- ehCabecalho: boolean
TDefinicaoTipo
- tipoDefini cao: String- declaracaoDefinicao: String- tabelaVariaveis: TLi st- docComment: TComment
TDiretiva
- tipoDiretiva: string- codigo: String
- docComment: TComment
TEnumerador
- tipoEnumerador: String- declaracaoEnumerador: String- docComment: TComment
TFuncao
- tipoFuncao: String- declaracaoFuncao: String- tabelaVariaveis: TLi st- tabelaStructs: TList- tabelaUnioes: TLi st- commentSetado: boolean
- docComment: TComment
TVariavel
- tipoVariavel : String- declaracaoVariavel: String- docComment: TComment
TUniaoStruct
- tipoUniaoStruct: String- declaracaoUniaoStruct: String- tabelaVariaveis: TLi st- tabelaUnioesStructs: TList- docComment: TComment
TInclude
- nomeArquivo: string- extensaoArquivo: String
- docComment: TComment
0..*
1..*
0..*
0..*
1..*1
1
1
1
1
1
1
7/24/2019 Documentando c
14/31
Anlise e adaptao da gramtica C ANSI
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Anlise e adaptao da gramtica C ANSI
Construes previstas pelo C ANSI, includas
Declarao de tipos derivados e de variveis a partir dos tipos derivados
Declarao de estruturas (struct, union) internas a funes
Inicializao dearraysquando da declarao
Definio de tipos (typedef) contendoarrays
struct RegistroProduto { int codigoProduto; };
int main() { RegistroProduto produto; }
int main() { struct RegistroProduto { int codigoProduto; }; }
int valores[] = {1, 2, 3, 4, 5};
typedef char[5] nome;
7/24/2019 Documentando c
15/31
Definio de tipos (typedef) contendo estruturas (struct, union)
Definio de enumeradores (enum) acompanhados apenas de um identificadorou de uma listas de identificadores
typedef struct nodo { char x; int y;};
Anlise e adaptao da gramtica C ANSI
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Anlise e adaptao da gramtica C ANSI
enum x; enum {x=1, y=2};
Construes previstas pelo C ++
Declarao e inicializao de variveis nos argumentos do comando for
for (int lin=0; lin
7/24/2019 Documentando c
16/31
Especificao da linguagem de DocComments
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao da linguagem dedoccomments
Comentrios para documentao
TagsGDC Dezesseis tags
Baseados no JavaDoc e nas sugestes do professor Maurcio C. Lopes Case sensitive Portugus
TagsHTML
/*@
@cabealho:
@autor: Vilmar Orsi
@verso: Beta 1.0
@entrada: Um nmero inteiro
*/
Especificao Lxica, Sinttica e Semntica
7/24/2019 Documentando c
17/31
Especificao da linguagem de templates
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao da linguagem detemplates
Motores de templates FastTrac Velocity
Linguagem de templates
Case sensitive Portugus Identificadores, Componentes, Propriedades e Comandos
Especificao
Lxica, Sinttica e Semntica
#para-cada (@include)
#defina (@comentrio = @include.comentrio)
Arquivo includo: @[email protected]
#se(@comentrio.possui(@autor))
Autor: @comentrio.autor
#fecha
#fecha
7/24/2019 Documentando c
18/31
Especificao do modelo de templates
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao da linguagem de templates Especificao do modelo de templates
Os modelos de templatesso compostos por Um arquivo descritor do modelo de templates(.TEM) Um ou mais arquivos HTML contendo cdigo esttico e dinmico
arquivo_frame\index.html #complemento(_index.html)
arquivo_frame\menu.html #complemento(_menu.html)
arquivo_frame\conteudo.html #complemento(_sobre.html)
7/24/2019 Documentando c
19/31
Especificao da ferramenta
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao da ferramenta
Entreprise Architect Conceitos de orientao a objetos UML Diagrama de casos de uso Diagrama de classes
Usurio
UC01 - Gerar
documentao
UC02 - Elaborar
templates
UC03 - Inserir
DocComments
Diagrama de Casos de uso
7/24/2019 Documentando c
20/31
Diagrama de Classes
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao da ferramenta Diagrama de Classes
Pacotes
Analisador de cdigo fonte C
Analisador de templates
Analisador de DocComments
Excees
7/24/2019 Documentando c
21/31
Pacotes
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Especificao Especificao da ferramenta Diagrama de Classes Pacotes
Analisador do cdigo fonte C
TCommentScanner
TAnalisador
TParser
TArquivo
TToken
TScanner
TSemantico
Legenda:
Geradas pelo GALS
Geradas pelo GALS e
modificadas
Implementadas
7/24/2019 Documentando c
22/31
Implementao
Tcnicas e ferramentas utilizadas Object Pascal Delphi
GALS
Implementao Analisadores do cdigo fonte C e dosDocComments Anlise dos templatese gerao da documentao
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Implementao
7/24/2019 Documentando c
23/31
Operacionalidade
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Implementao Operacionalidade
Interface de trabalho com arquivos
7/24/2019 Documentando c
24/31
Operacionalidade
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Implementao Operacionalidade
Interface de trabalho com modelos de templates
GERADOR DE DOCUMENTAO PARA LINGUAGEM C UTILIZANDO TEMPLATES
7/24/2019 Documentando c
25/31
Operacionalidade
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Implementao Operacionalidade
Interface de insero de DocComments
GERADOR DE DOCUMENTAO PARA LINGUAGEM C UTILIZANDO TEMPLATES
7/24/2019 Documentando c
26/31
Resultados e discusso
Trs verses
Testes
Implementao Acadmicos de Cincias da Computao e Sistemas de Informao
Avaliado atravs de questionrio com 16 questes 25 acadmicos
13 de Cincias da Computao 12 de Sistemas de Informao
A avaliao foi positiva Destacou a qualidade do GDC
Promoveu a participao dos alunos
Os erros reportados foram analisados e observou-se que tratavam-se de errosna escrita dos DocComments
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Resultados e discusso
GERADOR DE DOCUMENTAO PARA LINGUAGEM C UTILIZANDO TEMPLATES
7/24/2019 Documentando c
27/31
Comparativo
JavaDoc
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Ferramenta
Gerador dedocumentaodo C#
CDoc
Doxygen
Tagsdaferramenta TagsHTMLFormatoda sadaUso detemplatesLinguagem
Java Sim SimHTMLNo
C# Sim
No, masno h
limites paraos XMLs
XMLNo
CC++Java
No NoHTMLNo
No
CC++
JavaObjective C
HTMLRTF
PDFXML
Sim No
Voc est em: Resultados e discusso Comparativo
GDC C ANSI Sim HTML Sim Sim
GERADOR DE DOCUMENTAO PARA LINGUAGEM C UTILIZANDO TEMPLATES
7/24/2019 Documentando c
28/31
Concluso
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Concluso
Marcaes especiais Comentrios de blocos Delimitam informaes
Documentao no formato HTML Templates
Para cdigos fonte no comentados Documentao com caractersticas bsicas
Para cdigos fonte comentados Documentos mais complexos
GERADOR DE DOCUMENTAO PARA LINGUAGEM C UTILIZANDO TEMPLATES
7/24/2019 Documentando c
29/31
Informaes para documentao Anlise e coleta de informaes no cdigo fonte dos programas em C Tabela de smbolos
Todos ostokensreconhecidos no cdigo fonte Comentrios DocComments
Templates
Modelos de templates Documentao gerada padronizada
Liberdade de selecionar informaes e ordem de apresentao
Concluso (continuao)
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Concluso
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
7/24/2019 Documentando c
30/31
Extenses
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
Voc est em: Extenses
Melhorar a insero deDocComments
Melhorar as mensagens de erros
Implementar um editor grfico para os templates
Informar quais funes de um include esto sendo utilizadas
Implementar um controle de verses
Adaptar a ferramenta permitindo a gerao do algoritmo do programa
Incluir na ferramenta a opo de seleo de idioma
Especificar e implementar um motor de templatesgenrico para Delphi
GERADOR DE DOCUMENTAO PARA LINGUAGEM C, UTILIZANDO TEMPLATES
7/24/2019 Documentando c
31/31
,
Obrigado!!!