Documentando c

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


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


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


Voc est em: Introduo


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


Voc est em: Objetivos do trabalho


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


Voc est em: Fundamentao terica


6/31

Documentao de software


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


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


8/31

Analisadores de linguagens de programao


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


9/31

Motores de 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


10/31

Desenvolvimento do trabalho


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


11/31

Requisitos da ferramenta


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


12/31

Identificao das informaes para a documentao


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"


13/31

Especificao das estruturas de dados


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


TVariavel

- tipoVariavel : String- declaracaoVariavel: String- docComment: TComment

TUniaoStruct

- tipoUniaoStruct: String- declaracaoUniaoStruct: String- tabelaVariaveis: TLi st- tabelaUnioesStructs: TList- docComment: TComment

TInclude

- nomeArquivo: string- extensaoArquivo: String


0..*

1..*

0..*

0..*

1..*1

1

1

1

1

1

1


14/31

Anlise e adaptao da gramtica C ANSI


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;


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


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


16/31

Especificao da linguagem de DocComments


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


17/31

Especificao da linguagem de 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


18/31

Especificao do modelo de 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)


19/31

Especificao da ferramenta


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


20/31

Diagrama de Classes


Voc est em: Especificao Especificao da ferramenta Diagrama de Classes

Pacotes

Analisador de cdigo fonte C

Analisador de templates

Analisador de DocComments

Excees


21/31

Pacotes


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


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


Voc est em: Implementao


23/31

Operacionalidade


Voc est em: Implementao Operacionalidade

Interface de trabalho com arquivos


24/31

Operacionalidade



Interface de trabalho com modelos de templates

GERADOR DE DOCUMENTAO PARA LINGUAGEM C UTILIZANDO TEMPLATES


25/31

Operacionalidade



Interface de insero de DocComments



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


Voc est em: Resultados e discusso



27/31

Comparativo

JavaDoc


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



28/31

Concluso


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



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)


Voc est em: Concluso



30/31

Extenses


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



31/31

,

Obrigado!!!

Documents

Documentando c