Comentario de resumen de Visual Studio XML en una sola línea

Question

En Visual Studio, ¿cómo cambio el fragmento de comentario de resumen XML predeterminado de tres líneas a una línea?

Actualmente Proporciona este fragmento cuando escribo ///:

/// <summary> 
/// 
/// </summary> 

me gustaría este fragmento más corto:

///<summary></summary> 

Mis resúmenes son a menudo breves y la línea adicional 2 son innecesarias.

¿Hay alguna configuración de configuración para este o algún código personalizable/complemento personalizado para solucionarlo?

Answer 1

Esta es una pregunta anterior, pero me gustó la sugerencia de Jason Williams de crear un fragmento para esto, así que lo hice. No es muy complicado, pero copiar y pegar es aún más fácil :)

<?xml version="1.0" encoding="utf-8"?> 
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet"> 
    <CodeSnippet Format="1.0.0"> 
    <Header> 
     <Title>Single line summary</Title> 
     <Shortcut>summary</Shortcut> 
    </Header> 
    <Snippet> 
     <Code Language="csharp"> 
     <![CDATA[/// <summary>$end$</summary>]]> 
     </Code> 
    </Snippet> 
    </CodeSnippet> 
</CodeSnippets> 

Puede cambiar el acceso rápido (probablemente obviamente) cambiando el valor <Shortcut>.

Pega eso en un nuevo archivo llamado SingleLineSummary.snippet y guárdalo en la carpeta %USERPROFILE%\Documents\Visual Studio 2012\Code Snippets\Visual C#\My Code Snippets (modifica para que se ajuste a tu versión de Windows y Visual Studio).

Si no está familiarizado con los fragmentos, para usar esto simplemente coloque el cursor sobre un método/propiedad/etc, comience a escribir summary, y luego presione TAB un par de veces.

Answer 2

Puede formatear manualmente el comentario como más le guste, siempre que siga siendo válido xml.

El enfoque más barato podría ser deshabilitar la acción automática de creación de comentarios en Visual Studio (Herramientas> Opciones> Editor de texto> C#> Generar comentarios de documentación XML para ///) y usar un fragmento de código para insertar /// <summary></summary>.

Si desea que el formato predeterminado sea una sola línea y/o ayude a mantener el formato ordenado y legible, mi complemento Atomineer Pro Documentation también puede ser de su interés. Entre las muchas opciones, hay una que usa un formato compacto de 1 línea para cualquier comentario que sea lo suficientemente corto como para caber en una sola línea. Está diseñado específicamente para hacer esto, por lo que puede funcionar mejor para sus necesidades.

Una sugerencia final es que hay muchos otros complementos (Resharper, etc.) que pueden generar comentarios de doc xml. Creo que algunos de estos complementos se pueden configurar para usar un fragmento de texto en particular. Si ya tiene dicho complemento, es posible que el suyo se pueda ajustar para proporcionar el formato de una línea que necesita, de una manera ligeramente más avanzada que la que es posible con el ajuste básico de Visual Studio sugerido anteriormente.

Answer 3

Personalmente, creo que esto debería ser parte del editor VS en sí. Tengo created a ticket at user voice que puede elegir votar, si lo desea.

Mientras tanto, la idea del fragmento es buena, pero el comportamiento es ligeramente diferente. Si desea mantener el mismo comportamiento y si está dispuesto a comprar un complemento de terceros, entonces SubMain tiene un producto llamado "GhostDoc Pro" que, con un poco de esfuerzo, lo hará por usted. (Tenga en cuenta que tienen una versión gratuita, no "profesional", "GhostDoc", pero no creo que funcione).

Si desea seguir esta ruta, así es cómo funciona.

1. Después de instalar GhostDoc Pro, vaya a su menú de Herramientas. En la parte superior habrá un nuevo submenú desplegable, "GhostDoc Pro".
2. Vaya a Herramientas -> GhostDoc Pro -> Opciones -> Reglas

3. Usted tendrá que modificar la plantilla T4 para cada tipo que desea que esto tenga efecto sobre.

   1. Haga clic en la regla y después haga clic en "Editar"

   2. En la parte superior, modifique

      /// <summary> 
      ///<# GenerateSummaryText(); #> 
      /// </summary> 
      

      ser sólo

      /// <summary><# GenerateSummaryText(); #></summary> 
      

   3. En el método GenerateSummaryText, modificar cada this.WriteLine para ser solo this.Write
   4. Pulse Aceptar para guardar, pasar a la siguiente plantilla.

4. Antes de cerrar la página de opciones, diríjase a "General" (desde "Reglas") y verifique "Resalte el resumen generado automáticamente cuando Documento esto". Esto hará que el auto-texto recién insertado sea seleccionado del bate así que si no te gusta, puedes simplemente comenzar a escribir. Por supuesto, si prefiere que el texto no se genere en absoluto, puede hacerlo también, pero tendrá que modificar las plantillas T4 un poco más. En concreto, se tendrá que tener GenerateSummaryText sólo tiene que utilizar una sola línea,

   this.Write(Context.ExecMacro("$(End)")); 
   

   Esto tendrá que no genera ningún texto, pero nos ubicará entre los 2 <summary> etiquetas.

---

Nota al margen:

Si alguien sabe de una manera de conseguir ReSharper o cualquier otro complemento de herramientas para hacer esto, yo estaría interesado en ver que la solución también - si sin más motivo que la simple curiosidad.