Какова цель тега remarks в c#

Я понимаю, что тег remarks используется для предоставления дополнительной информации о классе, но он не отображается в intellisense при наведении / вызове этого класса. Я хотел бы знать, где именно это полезно?

11
.net c# xml-comments xmldocument

4 ответов

Примечания используются для создания файла документации. Они используются для более подробных комментариев, добавляя дополнительную информацию к тегу "summary" (тег "summary" отображается в intellisense).

сгенерированный файл документации будет иметь формат XML.

для создания файла документации необходимо добавить параметр компилятора" /doc". В visual studio можно включить создание XML-файла документации с помощью:

  1. щелкните правой кнопкой мыши проект имя -> свойства
  2. перейдите на вкладку Build
  3. включить (проверить), параметр XML documentation file
8

многие теги в .NET действительно используются при создании документации. Возможно, самый популярный и тот, который я использую, - это Sandcastle.

вот один довольно старый пост в блоге, обсуждающий эту тему, но вы получите точку:

" большинство разработчиков, я думаю, знают о концепции использования комментариев XML-кода для украшения объектов .NET. Есть действительно два преимущества: 1) он показывает эту информацию в intellisense, когда вы потребляете объект и 2) Вы можете производить документация компонентов, например MSDN."

источник : комментарии XML-кода и Sandcastle, демистифицированные!

3

Эти теги используются Visual Studio IntelliSense намекать о классах, функциях и свойствах, которые вы создаете, если они созданы правильно следующим образом:

на C# (и с редактором кода Visual Studio) это легко сделать, введя /// (три косых черты вместо двух) и нажатие кнопки Return.

это создаст "комментарии XML" и добавит наиболее распространенные теги для вас (например, теги параметров для каждый параметр метода).
если курсор находится над классом, он создаст <summary> тег, если он выше метода, он создаст дополнительно <param> теги для каждого параметра, а <returns> тег для возвращаемого значения.

другие, такие как <remarks> затем предлагаются IntelliSense, пока курсор находится внутри /// комментарии (см. пример ниже). Насколько мне известно, только <summary> и <param> теги используются IntelliSense. Если любой из этих тегов содержит a , вы можете ссылаться на другие элементы (как показано в Примере).

кроме того, как объясняют другие ответы, вы можете создать XML-документации который может быть преобразован в документ с гиперссылкой или статические html-файлы с помощью сторонних инструментов (например,Sandcastle Help File builder).

пример:

/// <summary>
/// Description what the class does
/// </summary>
public class MyClass
{
    /// <summary>
    /// Description what the function does
    /// </summary>
    /// <param name="param1">Description what the parameter does 
    ///   Optional tags inside param1:
    ///    <c></c> <code></code> <list type=""></list> <paramref name="param1"/>
    ///    <para></para>
    /// </param>
    /// <param name="param2">Description what the parameter does</param>
    /// <returns>Description about the return value</returns>
    public string MyMethod(int param1, string param2)
    {
        return "Some value: " + MyProperty;
    }

    /// <summary>
    /// Description what the property does
    /// </summary>
    /// <see cref="MyMethod(int, string)"/>
    string MyProperty { get; set; }

    // optional tags (valid for class and methods):

    /// <completionlist cref=""/>
    /// <example></example>
    /// <exception cref=""></exception>
    /// <include file='' path='[@name=""]'/>
    /// <permission cref=""></permission>
    /// <remarks></remarks>
    /// <see cref=""/>
    /// <seealso cref=""/>
}
2

как можно прочитать в Руководство C#:

тег используется для добавления информации о типе, дополняя указанную информацию <summary>. Эта информация отображается в окне обозревателя объектов.

Так <summary> для компактного описания элемента и <remarks> для полного описания. При написании кода intellisense покажет сводку, но в документации или более подробных представлениях Примечания содержимое будет показано. Отображение полного описания с помощью intellisense займет много места и времени, чтобы прочитать его.

0