Documentação de Código .Net

O Presente artigo explica como gerar uma documentação de todo o código .Net.

por Antonio Lucas Finotti Pereira

Este artigo mostra como podemos criar uma documentação do código desenvolvido em .Net, para esta documentação vamos precisar de alguns softwares, ambos são gratuitos. Abaixo segue o nome e o link para download.

· HTML Help Workshop

http://download.microsoft.com/download/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe

· Sandcastle Help File Builder GUI (Baixar e instalar os 2 links)

http://shfb.codeplex.com/

http://sandcastle.codeplex.com/

Modelo de Documento Gerado

Abaixo segue um modelo do documento gerado pelo Sandcastle.

Instalação

Abaixo segue os passos que deverão ser seguidos para utilizar este tipo de documentação:

Descrição	Arquivo
HTML Help Workshop	1 - htmlhelp.exe
Sandcastle Help File Builder GUI	2 - SandcastleBuilderSetup.msi
Sandcastle Atualização	3 - Sandcastle.msi

Os arquivos deverão ser instalados na seqüência mostrada neste documento, o primeiro a ser instalado deverá ser o HTML Help Workshop, pois o SandCastle Help File Builder GUI utiliza várias funções do HTML Help e o SandCastle Atualização possui alguns arquivos necessário para poder compilar e gerar a documentação do código.

Padrão de Documentação

Para o arquivo ser gerado corretamente, devemos documentar todo o código utilizando o próprio padrão de documentação do .Net.

Quando for documentar o código pressione a barra “/” 3 vezes [“///”], assim o .Net irá colocar os códigos necessários para a documentação automaticamente, você só terá que informar uma descrição.

Exemplo 1

Exemplo 2

Gerando o Documento

Para gerar o documento abra o SandCastle help file builder GUI, clique no menu File, em seguida selecione New Project, será exibida uma janela pedindo para você selecionar a pasta onde o documento será gerado e informar o nome do projeto.

Depois disso no Visual Studio abra seu projeto documentado para gerar um arquivo XML com a documentação. Clique no menu Project, em seguida selecione “nome do seu projeto” Properties..

Clique em Build.

Apenas selecione a opção [ XML documentation file], que por padrão vem desmarcada.

Após selecionar esta opção e salvar o projeto, é necessário dar um Rebuild Solution no projeto para o Visual Studio gerar o arquivo XML.

Agora vamos voltar para o SandCastle para finalizar a geração do documento. Abaixo segue a tela do SandCastle.

O Sand Castle disponibiliza várias propriedades para personalizar o documento, você pode alterar de acordo com sua necessidade. Abaixo segue a descrição de algumas:

Nome propriedade	Descrição/Exemplo
FrameWorkVersion	Versão do FrameWork – 2.0
HelpFileFormat	Formato do Documento – HtmlHelp 1
FooterText	Rodaté do Documento – Desenvolvimento
HeaderText	Cabeçalho do Documento – Antonio Lucas
Help Title	Titulo do Documento – Sistema teste
HtmlHelpName	Nome do Arquivo que será gerado – TesteDoc
DocumentInheritedMenbers	Utilizar herança na documentação – False

Agora é necessário vincular o arquivo XML (gerado pelo Visual Studio) neste projeto do Sand Castle. Na janela Project Explorer, clique o botão direito do mouse e selecione a opção Add Documentation Source...

Agora selecione o arquivo XML gerado pelo Visual Studio.

Depois de selecionado, o arquivo irá aparecer na janela Project Explorer, juntamente com o arquivo .exe do projeto. Abaixo segue um exemplo.

Agora vamos compilar o projeto para que o Sand Castle gera a documentação do código, para isso existem duas opções, o atalho ou clicando no menu Documentation.

	Clique em Buil Project para gerar o Documento.

Após dar um Build Project o Sand Castle exibe uma janela Build OutPut, mostra todo o trabalho que está sendo feito pelo Sand Castle, no final da compilação ele exibe um relatório informando o total de Tópicos, links, gráficos gerados e o caminho onde o documento final foi gravado.