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 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 para criar quebras de linha a partir do Visual studio 2019. Consulte a resposta aqui .

— precisa saber é

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

Observe que não há linha extra adicionada quando usamos em  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  não funciona, em vez usar/// <para> </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> </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

 e  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