Como adicionar uma quebra de linha na documentação do C # .NET

196

Isso deve ser muito mais fácil ...

Eu quero adicionar uma quebra de linha "codificada" à documentação XML no meu 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 você pode ver, encontrei algumas respostas que demonstraram a adição de colchetes <e>. Curiosamente, a boa quebra de linha 'ol <br /> não cria uma quebra de linha no pop-up do Intellisense.

Eu acho isso irritante ...

Alguma sugestão?

c# .net xml-documentation Tinkerer_CardTracker
fonte
3
É possível usar <br/> para criar quebras de linha a partir do Visual studio 2019. Consulte a resposta aqui .
precisa saber é

Respostas:

314

Você pode usar uma <para />marca para produzir uma quebra de parágrafo ou pode <para></para>agrupar o texto em marcas como uma maneira de agrupar o texto e adicionar a linha em branco após ela, mas não há equivalente a <br />nada parecido. (Que, de acordo com esta antiga postagem no fórum da MS, é por design.) Você pode obter a lista de tags disponíveis neste artigo de documentação da MS. Documentando seu código

Exemplo (com base na amostra 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
fonte
5
Aha! Agora estavam cozinhando! Obrigado! Isso está me incomodando há muito tempo ... Eu vi a opção para listada, mas assumi que era um atalho "paramater".
Tinkerer_CardTracker
2
não funcionou para mim. Usando o VB.NET no VS 2010, tentado com e sem a opção de parâmetro colorido do Powertools, as <para>tags são ignoradas e tudo é misturado em uma única linha no Intellisense. Encontrei esta pergunta, onde Hans explicou o problema: stackoverflow.com/questions/7070737/… .
Neolisk
1
Certifique-se de adicionar o fechamento tag </ para> bem =)
link64
85
O ruim disso é que ele realmente adiciona uma linha em branco inteira, em vez de apenas uma nova linha.
Devid 16/05
6
Então, alguém encontrou uma maneira de realmente inserir uma linha em vez de duas?
75

Este é o meu uso, tipo <br/>, está funcionando :)

/// <summary>
/// Value: 0/1/2
/// <para/>0 foo,
/// <para/>1 bar,
/// <para/>2 other
/// </summary>
IlPADlI
fonte
8
Por que esta resposta foi reduzida? Funciona, e parece ser uma solução muito melhor do que usar <para>&#160;</para>, <para>&nbsp;</para>ou o personagem invisível ...
Dinei
Isso funciona para novas linhas, mas não insere uma linha em branco entre itens como as outras opções.
Yushatak 12/09
15
Nas versões recentes do VS, <para/>parece adicionar uma linha em branco, não apenas uma quebra de linha.
Dinei
2
@IlPADlI, +1 como exemplo de uso. Trabalho confirmado no VS 2012 Ultimate Update 5.
Dennis T --Reinstate Monica--
9
VS 2017: linha em branco adicionado, e não simplesmente de quebra de linha ... amores certeza que a Microsoft dizendo-nos o que queremos fazer ...
Assimilater
39

A partir do Visual Studio 2019, use <br/>para novas linhas nos comentários.

Exemplo:

/// <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>

insira a descrição da imagem aqui

Observe que não há linha extra adicionada quando usamos em <br/>vez de <para>.

23bl
fonte
4
Ainda é útil porque esta pergunta é o principal resultado do google sobre como adicionar uma quebra de linha na documentação do C #.
Dan
27

Adicione uma <para>tag com um caractere especial, o caractere 255 ou invisível .

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

Funcionará assim:

insira a descrição da imagem aqui

Joel
fonte
8
Isso é útil, no entanto &nbsp;não funciona, em vez usar/// <para>&#160;</para>
Robert H
1
Pessoalmente, mantenho /// <para> </para>um lembrete. Então é só copiar e colar! (E funciona - pelo menos para mim)
Joel
2
Não sei por que, mas copiar e colar /// <para> </para>não funciona. /// <para>&#160;</para>trabalho!
Wenqiang
8
Em vez de usar a <para>marca entre blocos de texto, você deve usar a <para>marca em todos os parágrafos, exceto o primeiro no <summary>elemento. Para os <typeparam>, <param>, <value>, <exception>, e <returns>elementos, usá-los em torno de todos os números, se você tem mais de um (opcional se você tiver apenas um desses elementos). Para todos os outros elementos do bloco (inclusive <note>dentro de outro elemento do bloco), use <para>tags em todos os parágrafos, mesmo se você tiver apenas um.
Sam Harwell
1
Fonte: I autoria deste, incluindo a maior parte do estilo de apresentação: openstacknetsdk.org/docs-master/html/...
Sam Harwell
3

<br></br>e <br />parece não funcionar, e às vezes não se trata realmente de <para>separar as frases tanto quanto do desejo de ter uma linha em branco para a separação de preocupações. Estou mencionando isso aqui, porque esta pergunta parece ser a causa de muitas perguntas fechadas dessa natureza.

A única coisa que encontrei para trabalhar foi 

<para>&#160;</para>

Por exemplo

/// <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>

Resulta em

"This sentence shows up when the type is hovered"

int PrimaryKey

virtual Relation Relation
Travis J
fonte