It Devel Criando documentação em C# com doxygen (html e pdf)
Post
Cancel

Criando documentação em C# com doxygen (html e pdf)

Doxygen é um sistema  open-source para a geração de documentação e referência de código, o doxygen realiza a documentação de diversas linguagens como C#, C++, Java e etc. A documentação é gerada a partir de marcadores inseridos no próprio código-fonte.

Escolhi este sistema pelos motivos acima e por ser amplamente utilizado e documentado pela comunidade.

Vamos ao passo a passo, primeiro realize o download do doxygen a partir do site oficial e realiza a instalação em seu windows. A instalação não requer comentários pois é extremamente simples e não necessita personalização.

Existe diversas sintaxes para a utilização do doxygen , para este tutorial foi escolhida a de XML, todas as sintaxes podem serem encontradas no manual.

Segue abaixo um exemplo tipico da sintaxe de XML:

[sourcecode language="csharp"]/// <summary>
/// Exemplo de descrição da classe.
/// </summary>
class DoxygenSample
{
/// <summary>
/// Este método realiza a soma de 2 números
/// </summary>
/// <param name="a">Primeiro número a ser somado</param>
/// <param name="b">Segundo número a ser somado</param>
/// <returns>Retorna a soma dos 2 números passados via parâmetro (a + b)</returns>
static Int32 Sum(Int32 a, Int32 b)
{
return a + b;
}
}
[/sourcecode]

Vamos ao exemplo prático, crie um novo projeto em C# conforme exemplo abaixo:

[sourcecode language="csharp"]///
/// @file program.cs
/// <summary>
/// Decrição sucinta deste arquivo
/// </summary>
/// Descrição detalhada deste arquivo
/// Esta descrição pode ter mais de uma linha
/// Conforme este exemplo
/// @author Helvio Junior <helvio_junior@hotmail.com>
/// @date 26/10/2013
/// $Id: program.cs, v1.0 2013/10/26 17:44:13 Helvio Junior $

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace DoxygenSample
{
/// <summary>
/// Uma descrição sobre a classe Program
/// Você pode colocar o que deseja.
/// </summary>
class Program
{
/// <summary>
/// Método de inicialização do programa
/// </summary>
/// <param name="args">Como parâmetro é recebido os argumentos passados via linha de comando pelo usuário</param>
static void Main(string[] args)
{
Console.WriteLine(Sum(10, 30));
}

/// <summary>
/// Este método realiza a soma de 2 números
/// </summary>
/// <param name="a">Primeiro número a ser somado</param>
/// <param name="b">Segundo número a ser somado</param>
/// <returns>Retorna a soma dos 2 números passados via parâmetro (a + b)</returns>
static Int32 Sum(Int32 a, Int32 b)
{
return a + b;
}
}
}
[/sourcecode]

Para os comandos especiais do cabeçalho do arquivo pode ser consultado a documentação do doxygen

Agora que o código está pronto vamos a execução do doxygen. Abra o doxywizard, ele facilita bastante toda a configuração.

Na janela inicial configure as seguintes opções:

  • Diretório de execução (working directory)
  • Na aba Wizard
    • Nome do projeto (project name)
    • Sumário do projeto (project synopsis)
    • Versão do projeto (project version)
    • Diretório do código fonte (source code directory)
    • Selecione a opção scan recursivo (scan recursively)
    • Diretório de destino da documentação (destination directory)

Doxygen 001

Clique em next ou no item mode e configure as seguintes opções:

  • Todas as entidades (all entities)
  • Otimizado para C# (optimize for C# and java output)

Doxygen 002

Clique em Next ou em Output e configure conforme abaixo:

Doxygen 003

Clique em next ou em Diagrams e configure conforme abaixo:

Doxygen 004

Por último clique na aba Expert depois em build e selecione todas as opções conforme imagem abaixo:

Doxygen 005

Toda a configuração está pronta, basta agora ir na aba run e clique no botão run doxygen:

Doxygen 006

Para visualizar a documentação clique em Show HTML output. A documentação gerada é semelhante as imagens abaixo:

Doxygen 007

Doxygen 010

Doxygen 008

Para gerar a documentação em PDF é necessário a instalação do Miktex disponível no site oficial http://www.miktex.org/.

Após a geração da documentação através do doxygen 2 sub-diretórios são criados dentro diretório escolhido para saída da documentação (html e latex) onde HTML tem a documentação mostrada acima e o latex é a preparação para a geração do PDF.

Após a instalação do miktex, entre no diretório latex e execute o arquivo bat nomeado make.bat o arquivo refman.pdf será gerado.