Como gerar documentação automaticamente em .NET?

Gerar documentação para os projetos de desenvolvimento nem sempre são tratadas como importantes. Nem todos pensam (ou sabem pensar) que o legado do projeto é da empresa e não do programador. A solução de documentação que quero falar é muito boa e eficiente, independente do projeto em questao ter a documentação como um artefato formal.

Sandcastle - Help File Builder

Esta solução gera documentação apartir dos comentários de 3 barras feito no código. A documentação gerada é semelhante a documentação do MSDN ou dos SDKs em documentos HTML ou CHM (Help do Windows).

/// <summary> /// Responsável por realizar cálculos /// </summary> public class Calculadora {     /// <summary>     /// Útil para realizar somatório de números inteiros     /// </summary>     /// <param name="i">Primeiro número a participar do somatório</param>     /// <param name="j">Segundo número a participar do somatório</param>     /// <returns>Retorna a soma entre dois valores</returns>     int soma(int i, int j)     {         return i + j;     } }

Faça download do SandCastle

http://shfb.codeplex.com/

Como instalar o SandCastle?
1: Faça download do instalador, descompacte e execute-o

Instalação do SandCastle

2: Avance a instalação

Avance e leia atentamente todos os pontos da instalação.

Quando chegar em "SandCastle Pacth" clique em "Apply Patch"

Configurando a instalação do SandCastle

3: Avance a instalação, novamente
Prossiga até chegar em "SandCastle Help File Builder" clique em "Install SHFB"

Instalando o SandCastle Help File Builder

SandCastle Help File Builder

4: Feito.

SandCastle instalado com sucesso.
Reinicie seu computador.

Instalação do SandCastle finalizada

Como preparar meu projeto do visual studio para gerar documentação?
1: Crie seu projeto com comentários de 3 barras

Como demonstrado no inicio do artigo.

2: Configure o projeto

Vá no "Solution Explorer" do seu projeto e clique em Propriedades

Selecionar: Propriedades do Projeto

Vá na aba "Build" e selecione o checkbox "XML documentation file"

Na aba Build, selecionar XML Documentation

3: Compile seu projeto

Vá até o local onde está o executavel ou DLL do projeto. 

Você deve encontrar um documento XML com os comentários


4: Pronto

Como utilizar o SandCastle?
1: Abra a aplicação do SandCastle
Encontra-se no menu iniciar > SandCastle Help File Builder > SandCastle Help File Builder GUI

SandCastle Help File Builder GUI

2: Crie um novo projeto
Vá no menu "File" > "New Project" e escolha um local para salvamento de seu novo projeto

Criando Projeto no SandCastle

3: Adicione arquivos para geração da documentação

Vá na aba "Project Explorer" encontrada, inicialmente, à direita.

Clique com o botão direito em "Documentation Sources" e escolha as DLLs de seus projetos e XMLs de seus comentários

Adicionando DLLs e XMLs no SandCastle

4: Gere a documentação

Vá no menu "Documentation" > "Build" e espere.

O sistema gerará logs visíveis na tela e mostrará um barra de progresso no canto inferior direito.

Gerando arquivo CHM de ajuda

5: Leia a documentação gerada

Vá na pasta onde o projeto do SandCastle, criado no passo 1, foi salvo. Encontre uma pasta chamada Help e abra o arquivo "Documentation.chm"

Abrindo arquivo .CHM gerado automáticamente

6: Pronto
Sua documentação foi gerada com sucesso

Abrindo o arquivo .CHM gerado automáticamente com base nos comentários

Obs.: Esta tarefa pode demorar. Por exemplo, tenho um documento de uns 100 métodos comentados, e umas 20 classes. Para gerar a documentação demora de 5 a 10 minutos, numa maquina de 2GB de ram.

É possível fazer diversas configurações no SandCastle. Está é a configuração mais básica. Num próximo post falo mais.