Cómo agregar un salto de línea en la documentación de C # .NET

196

Esto debería ser muuuucho más fácil ...

Quiero agregar un salto de línea "codificado" a la documentación XML en mi código

/// <summary>
/// Get a human-readable variant of the SQL WHERE statement of the search element. &lt;br/&gt;
/// Rather than return SQL, this method returns a string with icon-tokens, which 
/// could be used to represent the search in a condensed pictogram format.
/// </summary>

Como puede ver, encontré algunas respuestas que demostraron agregar corchetes <y>. Curiosamente, el buen salto de línea 'ol <br /> no crea un salto de línea en la ventana emergente Intellisense.

Encuentro esto molesto ...

¿Alguna sugerencia?

c# .net xml-documentation Tinkerer_CardTracker
fuente
3
Es posible usar <br/> para crear saltos de línea a partir de Visual studio 2019. Consulte la respuesta aquí .
23bl

Respuestas:

314

Puede usar una <para />etiqueta para producir un salto de párrafo o puede ajustar el texto en las <para></para>etiquetas como una forma de agrupar el texto y agregar la línea en blanco después, pero no hay equivalente <br />ni nada por el estilo. (Que según esta antigua publicación del foro de MS es por diseño). Puede obtener la lista de etiquetas disponibles en este artículo de documentación de MS. Documentando su código

Ejemplo (basado en la muestra OP original): 

/// <summary>
/// <para>Get a human-readable variant of the SQL WHERE statement of the search element.</para>
/// Rather than return SQL, this method returns a string with icon-tokens, which 
/// could be used to represent the search in a condensed pictogram format.
/// </summary>
pstrjds
fuente
55
¡Ajá! ¡Ahora estábamos cocinando! ¡Gracias! Esto me ha estado molestando durante mucho tiempo ... Vi la opción para listada, pero asumí que era un atajo "paramater".
Tinkerer_CardTracker
2
No funciono para mi. Al usar VB.NET en VS 2010, probado con y sin la opción de parámetros coloreados de Powertools, las <para>etiquetas se ignoran y todo se mezcla en una sola línea en Intellisense. Encontré esta pregunta, donde Hans explicó el problema: stackoverflow.com/questions/7070737/… .
Neolisco
1
Asegúrese de agregar también la etiqueta de cierre </para> =)
link64
85
Lo malo de esto es que en realidad agrega una línea en blanco completa, en lugar de solo una nueva línea.
Devid
66
Entonces, ¿alguien ha encontrado una manera de insertar realmente una línea en lugar de dos?
75

Este es mi uso, como <br/>, está funcionando :)

/// <summary>
/// Value: 0/1/2
/// <para/>0 foo,
/// <para/>1 bar,
/// <para/>2 other
/// </summary>
IlPADLI
fuente
8
¿Por qué se rechaza esta respuesta? Funciona, y parece ser una solución mucho mejor que usar <para>&#160;</para>, <para>&nbsp;</para>o el personaje invisible ...
Dinei
Esto funciona para líneas nuevas, pero no insertará una línea en blanco entre cosas como lo hacen las otras opciones.
Yushatak
15
En versiones recientes de VS <para/>parece agregar una línea en blanco, no solo un salto de línea.
Dinei
2
@IlPADlI, +1 para ejemplo de uso. Confirmado trabajando en VS 2012 Ultimate Update 5.
Dennis T --Reinstate Monica--
9
VS 2017: línea en blanco añadió, no simplemente línea de ruptura ... amores que Microsoft nos dice lo que queremos hacer ...
Assimilater
39

A partir de Visual Studio 2019, utilícelo <br/>para nuevas líneas en los comentarios.

Ejemplo:

/// <summary>
/// This is a comment.<br/>
/// This is another comment <br/>
/// This is a long comment so i want it to continue <br/> on another line.
/// </summary>

ingrese la descripción de la imagen aquí

Tenga en cuenta que no se agrega ninguna línea adicional cuando usamos en <br/>lugar de <para>.

23bl
fuente
44
Sigue siendo útil porque esta pregunta es el principal resultado de Google sobre cómo agregar un salto de línea en la documentación de C #.
Dan
27

Agregue una <para>etiqueta con un carácter especial, 255 caracteres o caracteres invisibles .

/// <summary>
/// Some text
/// <para>   </para>
/// More text
/// </summary>
/// <param name="str">Some string</param>
public void SomeMethod(string str) { }

Funcionará así:

ingrese la descripción de la imagen aquí

Joel
fuente
8
Esto es útil, sin embargo &nbsp;, no funciona, en su lugar use/// <para>&#160;</para>
Robert H
1
Yo personalmente mantengo /// <para> </para>una nota adhesiva. ¡Entonces es solo copiar y pegar! (Y funciona, al menos para mí)
Joel
2
No sé por qué, pero copiar y pegar /// <para> </para>no funciona en absoluto. /// <para>&#160;</para>¡trabajos!
wenqiang
8
En lugar de usar la <para>etiqueta entre bloques de texto, debe usar la <para>etiqueta alrededor de todos los párrafos, excepto el primero en el <summary>elemento. Para los <typeparam>, <param>, <value>, <exception>, y <returns>los elementos, los utilizan alrededor de todos los párrafos si tiene más de una (opcional si sólo tiene uno para estos elementos). Para todos los demás elementos de bloque (incluido el <note>interior de otro elemento de bloque), use <para>etiquetas alrededor de todos los párrafos, incluso si solo tiene uno.
Sam Harwell
1
Fuente: escribí esto, incluyendo la mayoría del estilo de presentación: openstacknetsdk.org/docs-master/html/…
Sam Harwell
3

<br></br>y <br />no parecen funcionar, y a veces no se trata realmente de <para>separar las oraciones tanto como del deseo de tener una línea en blanco para la separación de preocupaciones. Menciono esto aquí porque esta pregunta parece ser la causa de muchas preguntas cerradas de esta naturaleza.

Lo único que encontré para trabajar fue 

<para>&#160;</para>

Por ejemplo

/// <summary>
///     <para>
///         "This sentence shows up when the type is hovered"
///     </para>
///     <para>&#160;</para>
///     <para>int PrimaryKey</para>
///     <para>&#160;</para>
///     <para>virtual Relation Relation</para>
/// </summary>

Resultados en

"This sentence shows up when the type is hovered"

int PrimaryKey

virtual Relation Relation
Travis J
fuente