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)
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)
Clique em Next ou em Output e configure conforme abaixo:
Clique em next ou em Diagrams e configure conforme abaixo:
Por último clique na aba Expert depois em build e selecione todas as opções conforme imagem abaixo:
Toda a configuração está pronta, basta agora ir na aba run e clique no botão run doxygen:
Para visualizar a documentação clique em Show HTML output. A documentação gerada é semelhante as imagens abaixo:
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.