Skip Navigation Links
Novas Tecnologias
Ferramentas Adicionais
Ferramentas Adicionais
Gerando documentação XML : SandCastle
Data:10/5/2011

Translate this page now :





Categories: .NET

Gostou do texto ? Vote e dê sua opinião! Pontuação atual :
Adicione aos Favoritos!
BlogBlogs Rec6 Linkk Ueba Technorati Delicious DiggIt! StumbleUpon

Veja Também


 

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.

Veja abaixo os passos para gerar a documentação

Passo-a-Passo

  • Baixe o SandCastle - http://sandcastle.codeplex.com/
  • Configure o projeto para gerar documentação – /doc. Nas propriedades do projeto, tab “Build”, marque a opção “XML Documentation File”

SNAG-0129

  • Copie o arquivo .bat para o diretório debug da sua aplicação.
  • Faça um rebuild (precisava colocar esse passo ;-)
  • Abra um prompt na pasta debug (shift + right click no windows explorer é seu amigo)
  • Rode o .bat :  > Documentar NomeDoProjeto

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



Categories: .NET


Nome :
E-mail:
Comentarios :
 
 
Os Últimos Comentários
Nenhum comentário foi realizado ainda. Seja o primeiro !
Dicas
Dica do Dia
Receba Dicas Por Email
E-mail :  
 


 (help)
Aceito receber informativos do devASPNet, informações de eventos e treinamentos

Veja Quais Informativos Você Receberá

Pesquisar Dicas
Pesquisar Artigos, Dicas e Noticias

Banco de Dados
Algumas Entrevistas
Links Importantes

Búfalo Informática, Treinamento e Consultoria
R. Alvaro Alvim, 37/920 Centro - Cinelândia - Rio de Janeiro Cep: 20031-010
Tel : (21) 2262-1368 (21) 9240-5134 E-mail : Contato@bufaloinfo.com.br