Как добавить разрыв строки в документации C # .NET

197

Это должно быть намного проще ...

Я хочу добавить «кодированный» разрыв строки в документацию XML в моем коде

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

Как видите, я нашел несколько ответов, которые продемонстрировали добавление скобок <и>. Интересно отметить, что хороший разрыв строки не создает разрыв строки во всплывающем окне Intellisense.

Я нахожу это раздражающим ...

Какие-либо предложения?

Tinkerer_CardTracker
источник
3
Начиная с Visual Studio 2019, можно использовать <br/> для создания разрывов строк. См. Ответ здесь .
23

Ответы:

317

Вы можете использовать <para />тег для создания разрыва абзаца или вы можете заключить текст в <para></para>теги как способ сгруппировать текст и добавить пустую строку после него, но не существует эквивалента <br />или чего-либо подобного. (Который в соответствии с этим старым сообщением форума MS предназначен для этого .) Вы можете получить список доступных тегов в этой статье документации от MS. Документирование вашего кода

Пример (на основе оригинального образца OP):

/// <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
источник
5
Ага! Теперь готовили! Спасибо! Это беспокоило меня долгое время ... Я видел перечисленный параметр para, но предполагал, что это был ярлык "paramater".
Tinkerer_CardTracker
2
Не работал для меня. Используя VB.NET в VS 2010, пробовал с опцией цветных параметров Powertools и без нее, <para>теги игнорируются, и в Intellisense все смешивается в одну строку. Нашел этот вопрос, где Ганс объяснил проблему: stackoverflow.com/questions/7070737/… .
Neolisk
1
Убедитесь, что вы также добавили закрывающий тег </ para> =)
link64
87
Плохая вещь в этом заключается в том, что он добавляет одну целую пустую строку вместо новой.
Девид
6
Так кто-нибудь нашел способ вставить одну строку вместо двух?
75

Это мое использование, вроде <br/>, это работает :)

/// <summary>
/// Value: 0/1/2
/// <para/>0 foo,
/// <para/>1 bar,
/// <para/>2 other
/// </summary>
IlPADlI
источник
8
Почему этот ответ опущен? Она работает, и , кажется, гораздо лучшим решением , чем использование <para>&#160;</para>, <para>&nbsp;</para>или невидимый характер ...
Dinei
Это работает для новых строк, но не вставляет пустую строку между вещами, как другие опции.
Юшатак
16
В последних версиях VS, <para/>кажется, добавляют пустую строку, а не просто разрыв строки.
Диней
2
@IlPADlI, +1 для примера использования. Подтверждена работа над VS 2012 Ultimate Update 5.
Деннис Т - Восстановить Монику -
9
VS 2017: добавлена ​​пустая строка, а не просто разрыв строки ... Microsoft наверняка любит говорить нам, что мы хотим сделать ...
Ассимилятор
41

Начиная с Visual Studio 2019, используйте <br/>для новых строк в комментариях.

Пример:

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

введите описание изображения здесь

Обратите внимание, что при использовании <br/>вместо <para>. Дополнительная строка не добавляется .

23bl
источник
4
Все еще полезно, потому что этот вопрос - лучший результат Google для того, как добавить разрыв строки в документации C #.
Дан
27

Добавьте <para>тег со специальным символом, 255 символом или невидимым символом .

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

Это будет работать так:

введите описание изображения здесь

Joel
источник
8
Это полезно, однако &nbsp;не работает, вместо этого используйте/// <para>&#160;</para>
Robert H
1
Я лично держу /// <para> </para>в записке. Тогда это просто скопировать и вставить! (И это работает - по крайней мере, для меня)
Джоэл
2
Я не знаю почему, но копировать вставить /// <para> </para>не работает вообще. /// <para>&#160;</para>работает!
Вэньцзян
8
Вместо того, чтобы использовать <para>тег между блоками текста, вы должны использовать <para>тег вокруг всех абзацев, кроме первого в <summary>элементе. Для <typeparam>, <param>, <value>, <exception>и <returns>элементов, использовать их по всем пунктам , если у вас есть более одного ( по желанию , если у вас есть только один для этих элементов). Для всех других элементов блока (в том числе <note>внутри другого элемента блока) используйте <para>теги вокруг всех абзацев, даже если у вас есть только один.
Сэм Харвелл,
1
Источник: я написал это, включая большую часть стиля презентации: openstacknetsdk.org/docs-master/html/…
Сэм Харвелл,
3

<br></br>и <br />кажется, что это не работает, и иногда дело не в том, чтобы <para>разделить предложения так сильно, как в желании иметь пустую строку для разделения проблем. Я упоминаю об этом здесь, потому что этот вопрос, кажется, является родителем для многих закрытых вопросов такого рода.

Единственное, что я нашел на работе, было

<para>&#160;</para>

Например

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

Результаты в

"This sentence shows up when the type is hovered"

int PrimaryKey

virtual Relation Relation
Трэвис Дж
источник