Autodocumentación .NET: XMLDoc+GhostDoc+Sandcastle - WarNov Developer Evangelist - Site Home - MSDN Blogs

Autodocumentación .NET: XMLDoc+GhostDoc+Sandcastle

Autodocumentación .NET: XMLDoc+GhostDoc+Sandcastle

  • Comments 5

Sin documentación, el software nace, crece, se vuelve spaghetti, desquicia a los developers y todos mueren.

Aquí una guía súper rápida para que la documentación no sea un pain, y además tener el motivador de que al final vamos a poder tener páginas de documentación estilo MSDN, usando la última versión de Visual Studio: la 2012.

Ingredientes:

  • Visual Studio 2012
    • No necesita presentación
  • Ghost Doc
    • Es una extensión para Visual Studio que genera comentarios de documentación XML automáticamente para métodos y propiedades, basándose en su tipo, parámetros, nombre y otra información contextual. Es un addin que además desinstala automáticamente versiones anteriores y las actualize con las nuevas que estemos instalando.
  • Sandcastle Help File Builder
    • Sandcastle es una herramienta creada por Microsoft y publicada Open Source en Codeplex para crear documentación Estilo MSD basándose en los assemblies .NET y sus comentarios XML asociados. Es un tool basado en línea de comandos y no tiene una GUI pre-definida. Así que la curva de aprendizaje es alta. Afortunadamente la aplicación Sandcastle Help Builder ha sido construida sobre Sandcastle para proveer un fácil manejo de todas las opciones que tiene Sandcastle, de tal manera que el uso sea parecido al del antiguo NDoc.
      La instalación de esta aplicación requiere varios paquetes preinstalados y configurados. Por eso viene con un wizard bastante amigable que ayuda a la configuración.

Una vez tenemos todo instalado, pasemos a observar cómo generar la documentación!

Leave a Comment
  • Please add 7 and 1 and type the answer here:
  • Post
  • Excelente una pregunta y como podria hacer para Visual Studio 2010

  • Great article, thanks! For the record, the v4 of GhostDoc (Beta available) allows to preview XML Comments immediately in Visual Studio. And the v4 Pro edition takes even further - can generate help file (CHM) with a single menu command - no more complexity of the Sandcastle command line :)

  • jummm, no me funcionó la documentación... hice tal cual lo del video, después me salieron muchos warnings, y al desactivar el checkbox de las propiedades del proyecto para el xml, no me salía ningun warning, sin embargo después de compilar varias veces me funcionó y estando checkeado la opcion del xml no me generó warning alguno. lo cual se me hace extraño.

    después fuí al SandCastle y agregué el xml, y mientras compilaba generó un error y no funcionó. tengo Visual Studio 2012 ultimate (trial).

    Generating reflection information...

    [C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe]

     MRefBuilder (v2.7.2.0)

     Copyright ¸ 2006-2012, Microsoft Corporation, All Rights Reserved

     Info: Loaded 1 assemblies for reflection and 1 dependency assemblies.

    MREFBUILDER : error : Unresolved assembly reference: Windows (Windows, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null) required by HelloWorld [C:\Users\Miguel\Desktop\Help\Working\GenerateRefInfo.proj]

       Last step completed in 00:00:05.3837

    </buildStep>

    <buildStep step="Failed">

  • Hola Claudio. En los sitios mencionados, aparecen también las versiones para 2010

  • Miguel, pudiste resolver el problema, he probado con varias configuraciones y no me falla.

Page 1 of 1 (5 items)