Como gerar documentação automaticamente em .NET?

Publicado em 4 de junho de 2011 por @anselme

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.

Thiago Anselme - Gerente de TI - Arquiteto de Soluções

Ele atua/atuou como Dev Full Stack C# .NET / Angular / Kubernetes e afins. Ele possui certificações Microsoft MCTS (6x), MCPD em Web, ITIL v3 e CKAD (Kubernetes) . Thiago é apaixonado por tecnologia, entusiasta de TI desde a infância bem como amante de aprendizado contínuo.