Как использовать встроенные комментарии для документирования членов в .NET?

Как я могу задокументировать участника, встроенного в .Net? Позволь мне объяснить. Большинство инструментов, которые извлекают документацию из комментариев, поддерживают некоторую встроенную документацию, в которую вы можете добавить краткую информацию после объявления члена. Что-то типа:

public static string MyField; /// <summary>Information about MyField.</summary>

Есть ли способ сделать это на С# или языках .NET?


.net c# documentation documentation-generation xml-documentation
person Curro    schedule 06.11.2008    source источник

Ответы (3)


arrow_upward
7
arrow_downward

Нет, ты не можешь. XML-комментарии поддерживаются только как комментарии на уровне блока, то есть они должны быть размещены перед документируемым элементом кода. Обычные инструменты для извлечения XML-комментариев из кода .NET не понимают, как анализировать подобные встроенные комментарии. Если вам нужна эта возможность, вам нужно будет написать свой собственный синтаксический анализатор.

person Scott Dorman    schedule 06.11.2008
comment
Doxygen поддерживает это, поэтому вам не нужно писать собственный парсер. - person Charles Ward; 25.09.2017

arrow_upward
2
arrow_downward

Для этого нет встроенного способа. Система документации XML является иерархической; он определяет связь между тегом <summary /> и данными, которые сразу за ним следуют.

person Robert S.    schedule 06.11.2008

arrow_upward
1
arrow_downward

Да, просто поставьте его ПЕРЕД тем, что вы хотите прокомментировать.

/// <summary>Information about MyField.</summary>
public static string MyField;
person GeekyMonkey    schedule 06.11.2008
comment
Я знаю, что могу поставить его раньше. Я спрашиваю, могу ли я поставить его после в той же строке. - person Curro; 06.11.2008
comment
Это не встроенный комментарий. - person Scott Dorman; 06.11.2008
comment
// указывает встроенный комментарий, а не /* для многострочного. Я думал, что вы это имели в виду. Нет, нельзя поставить ПОСЛЕ. Как компилятор узнает, что вы не хотите применять его к следующей строке? - person GeekyMonkey; 06.11.2008
comment
Большинство синтаксических анализаторов используют символ, чтобы понять, что документация ссылается на символ перед комментарием. Что-то вроде: общедоступная статическая строка MyField; //- ‹summary›Информация‹/summary› Когда синтаксический анализатор видит //-, а не ///, он знает, что это документация для уточняющего символа. - person Curro; 06.11.2008
comment
Это совершенно просто: комментарий, появляющийся после кода в той же строке, относится к предыдущему коду. Но нет, это не поддерживается комментариями XML. - person Ian Goldby; 12.03.2015