Os comentários em XML são muito úteis e fáceis de inserir no código. Provavelmente você mesmo já deve ter pensado : “Como extrair esses comentários em XML para gerar uma documentação ?”
Existe uma ferramenta chamada SandCastle que faz isso, mas seu uso não é trivial, o que faz com que poucos se aprofundem no assunto.
Justamente pelo fato do uso não ser trivial, crie um .BAT que simplifica muito o trabalho com o sandcastle.
Resultado
O SandCastle irá gerar uma pasta output contendo um .chm com a documentação do projeto, tanto contendo a estrutura das suas classes como seus comentários XML extraidos do código.
Imprevistos
O código do arquivo .BAT tenta contornar problemas de path, mas considera tudo instalado em seu caminho default. Se não estiver, precisará manipular o código e/ou contornar de outra forma.
Explicações Detalhadas
Veja mais detalhes sobre o parâmetro /doc : http://msdn.microsoft.com/en-us/library/f64ezf9b(v=vs.80).aspx
O SandCastle tem o mal hábito de não funcionar porque de fato são necessários 12 passos entre a compilação e a geração da documentação. São tais passos que estão ocultos no .BAT que criei. Veja os passo em http://blogs.msdn.com/b/sandcastle/archive/2006/07/29/682398.aspx
Pegadinha adicional : O VS por default gera o .xml com o nome do projeto, mas a ferramenta chamada BuildAssembler está configurada para usar por default um arquivo chamado comment.xml, exatamente com esse nome.
Para resolver, o .BAT que criei troca o nome do arquivo .xml
Código do Arquivo .BAT
(copie e cole em um arquivo .bat)
@Echo off
REM ******************* Testa o parâmetro *******************
if {%1}=={} (
@echo Por favor, informe o nome do assembly
goto End
)
REM ********************** Redefine o path *********************
set path=%path%;%DXROOT%productiontools
set TOOLSPATH=%ProgramFiles%
if exist "%ProgramFiles% (x86)" set TOOLSPATH=%ProgramFiles(x86)%
set PATH=%TOOLSPATH%\HTML Help Workshop;%TOOLSPATH%\Microsoft Help 2.0 SDK;%PATH%
REM ********************* Remove diretórios existentes *****************
if exist output rmdir output /s /q
if exist chm rmdir chm /s /q
REM ******************** Preparando arquivo de documentação ***************
if not exist %1.xml (
@echo Erro : Não há arquivo de documentação
goto End
)
if exist %1.xml copy /y %1.xml comments.xml
REM ********** Call MRefBuilder ****************************
MRefBuilder %2.dll /out:reflection.org
REM ********** Apply Transforms ****************************
XslTransform /xsl:"%DXROOT%\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org/xsl:"%DXROOT%\ProductionTransforms\AddFriendlyFilenames.xsl" /out:reflection.xml /arg:IncludeAllMembersTopic=true /arg:IncludeInheritedOverloadTopics=true
XslTransform /xsl:"%DXROOT%\ProductionTransforms\ReflectionToManifest.xsl" reflection.xml /out:manifest.xml
call "%DXROOT%\Presentation\vs2005\copyOutput.bat"
REM **************Generate an intermediate Toc file that simulates the 2005 TOC format.
XslTransform /xsl:"%DXROOT%\ProductionTransforms\createvstoc.xsl" reflection.xml /out:toc.xml
REM ************** Montar Pastas ***********************
call %DXROOT%\Presentation\Prototype\copyOutput.bat
REM ********** Call BuildAssembler ****************************
BuildAssembler /config:"%DXROOT%\Presentation\vs2005\configuration\sandcastle.config" manifest.xml
REM ********** Gerar HTML Help Project ****************************
XslTransform /xsl:%DXROOT%\ProductionTransforms\ReflectionToChmProject.xsl reflection.xml /out:Output\test.hhp
REM ********** Gerar a table of contents ****************************
XslTransform /xsl:%DXROOT%\ProductionTransforms\createvstoc.xsl reflection.xml /out:toc.xml
REM ********** Gerar as informações do projeto de help *******************
XslTransform /xsl:%DXROOT%\ProductionTransforms\TocToChmContents.xsl toc.xml /out:Output\test.hhc
XslTransform /xsl:%DXROOT%\ProductionTransforms\ReflectionToChmIndex.xsl reflection.xml /out:Output\test.hhk
REM ********** Executar o processamento do Help ****************************
hhc output\test.hhp
:End