Criando Help com NDOC

Resolvi escrever este artigo como forma de ajudar a todos os desenvolvedores que trabalham em equipe, produzem softwares ou mesmo distribuem o código fonte. A idéia de documentar os códigos que desenvolvo é um costume muito bom pois, depois de muito tempo, é possível que ele seja usado ou alterado por outra pessoa, talvez que nem mesmo participou do projeto no começo do desenvolvimento.

Existe uma ferramenta que pode gerenciar e criar documentação de todo o projeto, ou seja, do código fonte que foi desenvolvido. O Visual Studio.Net 2003 possui também uma ferramenta que gera páginas html. É uma boa ferramenta, mas não mostrarei como usá-la, essa outra ferramenta NDOC pode gerar páginas html ou mesmo .chm, que é a extensão de um help.

Para utilizar e instalar o NDOC, basta acessar o site http://ndoc.sourceforge.net/ ou http://sourceforge.net/project/showfiles.php?group_id=36057 para fazer download e instalar em sua máquina.

Depois de instalado, agora será com o desenvolvedor ou programador. Todo o código que for digitado dentro da ferramenta Visual Studio.Net 2003 é ótimo se for documentado; é uma boa prática de programação.

Praticando

Antes de tudo, crie um projeto web no VS 2003 chamado NDoc2003. Criei uma classe chamada NDoc.cs para mostrar a todos como funciona a ferramenta NDOC. Desenvolvi apenas um método chamado VerificarStatus() que retorna uma String qualquer. A figura mostra como ficou o código digitado.

Apenas um for de zero a dez armazenando em uma variável string para retornar depois. Perceba que a classe está comentada dentro das tags summary. O código da classe é bem simples e de fácil entendimento.

using System;<br /><br />namespace NDoc2003<br />{<br />	/// <summary><br />/// Classe NDOC para mostrar ao usuário as boas práticas para /// documentar<br />	/// o código desenvolvido. <br />	/// </summary><br />	public class NDoc<br />	{<br />		private String VerificarStatus()<br />		{<br />			string retorno = null;<br />			for (int i=0; i > 10; i)<br />			{<br />				retorno = "meu retorno "  i;<br />			}<br /><br />			return retorno;<br />		}<br />	}<br />}

Esse comentário dentro da tag summary é muito importante para gerar, depois, o help com index e pesquisa. Depois de criado o método dentro da classe NDoc.cs, vá ao início, em método ou uma linha antes, e cliquei três vezes nas barras ( /// ), que a ferramenta Visual Studio.Net 2003 já coloca as tags necessárias para serem comentadas.

Pronto, o método foi comentado descrevendo o que ele faz, quais os métodos estão referenciando e o tipo de retorno. Depois de comentado, clique com o botão direito em cima do projeto e vá para a opção propriedades para definir um xml de comentário.

Logo depois, irá aparecer uma outra tela menor chamada Property Pages. Existe uma pasta do lado direito com o nome Configuration Properties e por último, dentro dessa opção existe um campo chamado XML Documentation File. Coloque um nome na frente do campo para sair um arquivo xml depois do projeto compilado.

O nome que escolhi foi NDocXML.xml para a saída dos comentários feitos dentro do projeto. É bastante interessante isso no Visual Studio.NET; todas as saídas do projeto estarão dentro deste xml. Depois, clique em APLICAR e então em OK.

Compilei o projeto e o mesmo gerou um arquivo de acordo com o que foi solicitado na tela de properties. Segue o mesmo dentro da pasta do projeto.

Depois de instalado, o NDOC fica em seu menu iniciar. Vá até a opção 1.1 e clique para o programa começar a executar.

Cliquei no programa e uma tela com algumas funcionalidades foi aberta. É bem simples de utilizá-lo.

Existe o botão ADD do lado direito, no começo do programa. Clicando, o mesmo abrirá uma outra tela menor que serve para indicar ou referenciar a DLL do projeto.

Esse campo Assembly, é para referenciar a DLL do projeto. Clique no botão com três pontinhos do lado direito ( … ) e indique a DLL do seu projeto depois de compilada. Depois disso, clique apenas no Ok.

Depois de tudo isso estamos quase lá, para gerar o nosso help. É simples, depois, fazer uma configuração para saber se queremos um help ou apenas documentos web, ou help e documentos web. Ainda na tela principal do NDOC, é necessário mudar alguns parâmetros ou configurações.

No meu caso, quero que a aplicação crie apenas o help do código que desenvolvi dentro do projeto. Com isso, na opção OUTPUTTARGET escolhi o valor HTML HELP. É só clicar no botão ao lado de salvar chamado BUILD.

Depois disso, o build foi completo gerando um arquivo .chm dentro do diretório indicado.

Prontinho, depois disso é só verificar o arquivo .chm.

Espero ter ajudado.