Integrando a documentação gerada pelo NDoc com o Visual Studio.Net 2003

O NDoc, para quem não o conhece, é um software free (grátis) para geração de documentação de código fonte (classes, forms, páginas, controles ...) para o .Net.

por Avelino Ferreira Gomes Filho

O NDoc, para quem não o conhece, é um software free (grátis) para geração de documentação de código fonte (classes, forms, páginas, controles ...) para o .Net. Com ele você poderá gerar documentações idênticas ao do MSDN ou JavaDoc por exemplo. Um artigo bastante interessante sobre o tema foi escrito pelo Israel Aéce e pode ser acessado pelo seguinte endereço: http://www.linhadecodigo.com.br/artigos.asp?id_ac=152.

Visto isso, vamos ao que interessa.

É comum que todo desenvolvedor crie alguns artefatos (classes, projetos, soluções ...) que possam ser aplicados em diversos projetos. Também é muito comum que essas soluções mais genéricas sejam utilizadas por mais de uma pessoa na sua empresa. Que tal você distribuir um Help que fique dentro do VS.Net, para que outros desenvolvedores tirem suas dúvidas da forma mais rápida possível. Para tal você irá precisar de utilizar um pouco da sua rede para baixar alguns softwares. São Eles:

• NDoc - http://ndoc.sourceforge.net
• VBCommenter - http://www.gotdotnet.com/workspaces/workspace.aspx?id=112b5449-f702-46e2-87fa-86bdf39a17dd (Cria as TAGs de comentário e o arquivo XML de documentação automaticamente)
• HTML Help Workshop and Documentation - http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&DisplayLang=en (Ferramentas de Help da Microsoft)
• Visual Studio .NET Help Integration Kit - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwmscextendingnethelp.asp (Ferramenta de integração de Help com o VS.Net)
• H2Reg - http://www.helpware.net/mshelp2/h2reg.htm (Registrador de Help)

Uma vez que você já as tenha instaladas, mãos a obra.

Primeira coisa a fazer é documentar e compilar o seu código fonte. Lembre-se, quanto mais você escrever, mais fácil torna a utilização do seu sistema por outros desenvolvedores e mais prática ficará uma possível manutenção que você venha a fazer no futuro.

Veja um exemplo da documentação gerada com auxílio do VBCommenter.

Agora vamos gerar a documentação do nosso assembly utilizando o NDoc. Aqui segue um roteiro rápido.

1. Escolha o Assembly do seu projeto através do botão ADD.
2. Faça as suas configurações nas propriedades do NDoc. Na Documentation Type não se esqueça de escolher a opção VS.Net 2003.



As minhas configurações foram:

• AssemblyVersion = Assembly Version
• CleanIntermediates = True
• CollectionNamespace = Calculadora
• CopyrightHref = http://www.meuendereco.com.br
• CopyrightText = Todos os direitos reservados
• DocumentPrivates = True
• FeedBackEmailAddres = avelinoferreiragf@gmail.com
• GenerateCollectionFiles = True (Essa opção deverá estar marcada sempre como True)
• HTMLHelpName = Calculadora Simplex
• LangID = 1046 (Português - Brasil)
• Output Directory = C:\VSNet2003\
• RegisterTitleAsCollection = True
• RegisterTitleWithNamespace = True
• Title = Documentação da Calculadora Complexa
3. Salve o seu projeto NDoc.
4. Construa a documentação (Build Documentation).

Deverão ser gerados os seguintes arquivos:

Beleza. Você já tem a sua documentação NDoc para o Visual Studio .Net 2003, agora vamos colocá-la dentro dele.

Partindo do princípio que você já instalou o Visual Studio .NET Help Integration Kit, o HTML Help Workshop and Documentation e o H2Reg. Vamos registrar a sua documentação.

1. Feche qualquer janela do Visual Studio, MSDN ou help do Windows que esteja aberta.
2. Abra um prompt de comando e entre na pasta de instalação do H2Reg, no meu caso, C:\Arquivos de programas\Helpware\H2Reg



3. O meu projeto NDoc foi compilado na pasta C:\VSNet2003\
4. Vamos fazer o registro com o seguinte comando: H2Reg -r cmdfile=C:\VSNet2003\Calculadora SimplexCollection.h2reg.ini



5. Caso apareça uma tela extremamente rápida parecida com essa imagem abaixo, você obteve sucesso.



6. Abra o Visual Studio .Net. Deverá aparecer uma tela parecida com essa, ou ao iniciar o VS.Net ou quando você abrir o Help do mesmo.

Seu Help já está integrado com Visual Studio. Aproveite. Para visualizar os arquivos de ajuda do combinados com o VS.Net, abra o Internet Explorer e digite o endereço: ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm. Na página que abre em decorrência desta ação você verá todos os helps integrados e habilitá-los ou desabilita-los como desejar.

Já estarão disponíveis as famosas TAGs Summary quando estiver utilizando o auto completar. Ao pressionar F1, você irá cair no Help da sua classe. E tudo mais que uma ajuda integrada possa oferecer.