[SOURCE] Snippet Tool Extension For Visual Studio (C#/VB)

[Eleкtro]

¿Qué es esto?

Snippet Tool es una extensión para Visual Studio, la cual mediante un menú desplegable en el menú contextual del editor de código, nos ayudará a realizar pequeñas pero repetitivas tareas de documentación XML y Snippets, para C# y VB.Net.



Snippet Tool no es una herramienta completa de documentación XML.

La idea principal fue desarrollar una simple extensión que me ayudase a automatizar la creación de archivos Snippet desde el texto seleccionado en el editor (vease el comando "Create Snippet File" en el menú contextual),
despues, decidí añadírle algunas funcionalidad adicionales cómo se puede comprobar en la imagen, a modo de complemento para cubrir necesidades que otras extensiones profesionales de documentación XML, cómo por ejemplo Ghost Doc, no llevan a cabo.

La idea es utilizar dichas funcionalidades cómo complemento, en combinación de alguna otra extensión cómo la ya mencionada, Ghost Doc.

Características

• Automatización para la creación de archivos .snippet administrados por Visual Studio.
  


• Automatización para la inserción de diversos tags cotidianos relacionados con la documentación XML.
  


• Los comandos del menú se pueden invocar mediante combinaciones de teclas pre-establecidas, por ejemplo al presionar CTRL + E + R, el texto seleccionado se insertará en el tag <see cref="texto"/>.
  


• Compatible con la sintaxis de C-Sharp y VisualBasic.Net.
  

Demostración

Estas imágenes pertenecen a la versión 1.0

Ejemplo de compilación y renderizado de la documentación

Código (xml) [Seleccionar] Expandir

<member name="M:ConsoleApplication1.Program.TestFunc(System.Int32,System.Int32)">
   <summary>
   This is a test method that performs a loop.
   </summary>
   
   <example> This is a code example.
   <code>
   try
   {
       TestFunc(1, 10);
   }
   catch
   {}
   </code>
   </example>
   
   <param name="param1">
   An <see cref="T:System.Int32"/> that determines the first value of the <see langword="for"/> loop.
   Use <paramref name="param2"/> to assign the last value.
   </param>
   
   <param name="param2">
   An <see cref="T:System.Int32"/> that determines the last value of the <see langword="for"/> loop.
   Use <paramref name="param1"/> to assign the first value.
   </param>
   
   <remarks>
   For more information see <see href="https://msdn.microsoft.com/en-us/library/5kzh1b5w.aspx"/>
   </remarks>
   
   <seealso href="https://msdn.microsoft.com/en-us/library/5kzh1b5w.aspx"/>
</member>

Código Fuente

➢ Versión 1.3


Notas:
La extensión ha sido desarrollada con la SDK de Visual Studio 2013, obviamente es necesario disponer de las referencias de dicha SDK para editar el proyecto.
➢ Microsoft Visual Studio 2013 SDK

Descarga el instalador de la extensión (paquete VSIX)

Versión 1.0
➢ Para Visual Studio 2013
➢ (EXPERIMENTAL) Para Visual Studio 2010, 2012, o 2015

Versión 1.1
➢ Para Visual Studio 2013
➢ (EXPERIMENTAL) Para Visual Studio 2010, 2012, o 2015

Versión 1.3
➢ Para Visual Studio 2010, 2012, 2013 y 2015

Observaciones

Las combinaciones del teclado se pueden presionar desde cualquier editor, por ejemplo desde el explorador de soluciones, esto no es una mejora, sino un fallo de diseño que se intentaré solucionar en futuras versiones.

Si encuentran cualquier bug no duden en comunicármelo preferiblemente DEJANDO UN COMENTARIO EN ESTE POST en lugar de enviarme un email o mensaje privado, y trataré de solucionar el problema.

También estoy abierto a sugerencias para implementar nuevas funcionalidades en la extensión, pero no voy a añadirle cosas típicas cómo por ejemplo soporte para insertar sumarios, ya que para eso está Ghost Doc (u otras extensiones).

Espero que les haya servido y gustado este aporte.

Un saludo!

[Eleкtro]

Nueva versión 1.1

Cambio de imagen, más comandos, y un panel de opciones en el menú herramientas de Visual Studio, ¡más y mejor!:



Added

• A properties page with name "Snippet Tools" inside the "Tools -> Options" menu.
  
• Paragraph command ( <para></para> tag ) with hotkey: Ctrl+E+Space.
  
• Separator Line command with hotkey: Ctrl+E+Tab.
  

Improved

• Simplified Command icons.
  
• Tag enclosing behavior when a full line is selected.
  

Fixed

• Keyboard shortcuts now are only avaliable when are pressed on the text editor.
  

Modified

• Keyboard shortcuts of "Hyperlink", "Hyperlink Alter" and "Remarks Section" commands.
  

[DarK_FirefoX]

Excelente idea, realmente fantástico. Lo descargué y lo probaré en un rato. Luego te digo que tal me fue.

Salu2s

[Eleкtro]

Excelente idea, realmente fantástico. Lo descargué y lo probaré en un rato. Luego te digo que tal me fue.

Salu2s

Vale , gracias.

Por curiosidad, ¿qué versión de VS utilizas?, me gustaría saber si la extensión se instala y funciona correctamente en VS2010, 2012 o 2015.

PD: Luego publicaré y compartiré un enlace de descarga desde la galería de extensiones de MSDN y quitaré el enlace de Mediafire, así se podrá descargar e instalar desde allí o también desde la IDE de Visual Studio directamente.

Saludos

[DarK_FirefoX]

Vale , gracias.

Por curiosidad, ¿qué versión de VS utilizas?, me gustaría saber si la extensión se instala y funciona correctamente en VS2010, 2012 o 2015.

Utilizo VS2013, todavía no he querido dar el brinco a VS2015.

Salu2s

[kub0x]

Grandísimo aporte  Descargando 

¿Cómo has conseguido realizar la documentación al estilo MSDN? Soy profano en documentación en C#, utilizo plugins, pero a la hora de exportar ni idea de como darle formato a la docu de las API que escribo.

Saludos!

[Eleкtro]

¿Cómo has conseguido realizar la documentación al estilo MSDN?

Es muy sencillo, te explico, de forma resumida:
La imagen de arriba es puro Html compilado con la herramienta HTML Help Compiler (hhc.exe) del paquete Microsoft HTML Help Workshop que puedes descargar gratuitamente desde MSDN;
los archivos de la estructura de archivos o filesystem (index.html, style.css, image.jpg, etc) son comprimidos y empaquetados en un archivo de ayuda con formato .chm (Microsoft Compiled HTML Help File).

La razón de que tenga un aspecto visual parecido a MSDN, es por que hoy en día existen muchas herramientas que además de ofrecer plantillas Html de ese estilo, automatizan dicha tarea de documentación Html para APIs, extrayendo los datos de las fuentee de documentación de una solución .Net mediante el uso de Reflection para los miembros no documentados mnualmente (ej: Int32), y de la documentación existente en los archivos de documentación XML generados por la solución de VS para los miembros que hayan sido documentados manualmente, claro está.

La herramienta que utilicé para compilar el ejemplo en la imagen de arriba, es la opción favorita que se puede encontrar dentro del software open-source:
➢ Sandcastle Help File Builder

De hecho, prefiero utilizar ese programa antes que cualquier software comercial craqueado, y sabes que de eso tengo un montón para .Net, jaja, pero SandCastle aun siendo gratuito es insuperable.
Por otro lado, para documentar la UI de una aplicación, sus características etc, es preferible usar herramientas más especializadas en esa tarea, cómo por ejemplo Help&Manual, Helpinator, o Dr. Explain, cada una de ellas tiene funcionalidades alucinantes, sobre todo la "captura" que realiza Dr. Explain sobre los elementos de una GUI (pruébalo, en serio). WinCHM también es útil, pero es muy simplón.

Para compilar en formato .chm, el cual es el formato de documentación offline más común, pues cómo ya he mencionado necesitarás disponer del compiler (hhc.exe) que viene incluido en el paquete Microsoft HTML Help Workshop:
➢ Microsoft HTML Help Downloads
(no recuerdo si el SandCastle incluye el hhc.exe, pero igualmente para utilizar otras herramientas de este tipo lo necesitarás por que no lo suelen incluir por defecto, es un requisito adicional)

Si deseas documentar la API en formato HxS entonces necesitarás el compiler del paquete Microsoft Help 2 pero no es descargable desde la MSDN, viene incluido en la instalación de VS2008, y está considerado cómo formato obsoleto, vaya, que no vale la pena interesarse por él.

También puedes compilar en formato .mshc para visualizarlo con la herramienta Microsoft Help Viewer que viene incluida en la instalación de VS.

EDITO: Ah, se me olvidó comentarte que además con la extensión GhostDoc puedes generar los archivos htm al estilo MSDN con el comando "Preview Comment" (pero no compilar un .chm).

Saludos!

[Eleкtro]

Nueva versión 1.3

( Descárgala en el comentario principal! )



Añadido

• Nuevo comando: Collapse Xml Comments
  
• Nuevo comando: Expand Xml Comments
  
• Nuevo comando: Delete Xml Comments
  

Corregido

• En la versión prevía, para deshacer una acción era necesario deshacerla 2 veces seguidas en algunos comandos.
  

Mejorado

• El comando Paragraph ahora puede añadir el tag vacío (<para></para>) si no hay texto seleccionado.
  
• El comando Remarks ahora puede añadir el tag vacío (<remarks></remarks>) si no hay texto seleccionado.
  
• Limpieza y refactorización general del código fuente.
  

Demostración de las nuevas características: