Комментарий в xml: XML — Комментарии — CoderLessons.com

Вставка комментариев XML-документации — Visual Studio (Windows)





Twitter




LinkedIn




Facebook




Адрес электронной почты










  • Статья



Применимо к: Visual Studio Visual Studio для Mac Visual Studio Code

Visual Studio может помочь вам документировать элементы кода, такие как классы и методы, автоматически формируя стандартную структуру комментариев для XML-документации. Во время компиляции можно создать XML-файл, содержащий комментарии для документации. Чтобы включить этот параметр, выберите Generate a file containing API documentation (Создать файл, содержащий документацию по API) на вкладке Сборка>Выходные данные в свойствах проекта.

Совет

Если вы хотите настроить нестандартное имя и расположение для файла документации, добавьте свойство DocumentationFile в файл .csproj, .vbproj или .fsproj.

Созданный компилятором XML-файл можно распространять вместе со сборкой .NET, чтобы Visual Studio и другие интегрированные среды разработки могли использовать IntelliSense для отображения кратких сведений о типах и элементах. Кроме того, XML-файл можно запускать с помощью таких средств, как DocFX и Sandcastle, и создавать веб-сайты со справочными сведениями по API.

Примечание

Команда Вставить комментарий, которая автоматически вставляет комментарии XML-документации, доступна в C# и Visual Basic. Однако можно вручную вставить комментарии XML-документации в файлы C++ и по-прежнему создавать файлы XML-документации во время компиляции.

  1. Поместите текстовый курсор над элементом, например методом, который нужно задокументировать.

  2. Выполните одно из следующих действий.

    • Введите /// в C# или ''' в Visual Basic

    • В меню Правка выберите IntelliSense>Вставить комментарий.

    • Щелкните правой кнопкой мыши или вызовите контекстное меню в редакторе кода или над ним и выберите Фрагмент кода>Вставить комментарий.

    Над элементом кода сразу же создается XML-шаблон. Например, при комментировании метода он создает <элемент сводки>, <элемент param> для каждого параметра и возвращаемый<> элемент для документирования возвращаемого значения.

  3. Введите описание для каждого XML-элемента, чтобы полностью задокументировать элемент кода.

Стили можно использовать в комментариях XML, которые будут отображаться в виде кратких сведений при наведении указателя мыши на элемент. К этим стилям относятся курсив, полужирный шрифт, маркеры и ссылка, доступная для щелчка.

Примечание

Существует параметр для переключения комментариев XML-документации после ввода /// в C# или ''' Visual Basic. В строке меню выберите Сервис>Параметры, чтобы открыть диалоговое окно Параметры. Затем перейдите в текстовый редактор>C# (или Visual Basic).> В разделе Справка редактора найдите параметр Создавать комментарии XML-документации.

См. также раздел

  • Документирование кода с помощью XML-комментариев (руководство по C#)
  • Практическое руководство. Создание XML-документации (Visual Basic)
  • Комментарии C++
  • XML-документация (C++)
  • Создание кода






XML-комментарии | Уроки C#



Блог начинающего специалиста


Каждый XML-комментарий в C#, начинается с трех слэшей «///», а в Visual Basic.NET с трех одиночных кавычек (апострофов) «’ ‘ ‘». В C#, обычные комментарии начинаются с двух слэшей, а третий слэш говорит синтаксическому анализатору, что это XML-комментарий. В барсике, аналогично, только обычный комментарий начинается с одной, одиночной кавычки.

Для чего же нужны XML-комментарии? 

Парсить XML-файл настоящий кайф, то бишь, ничего сложного в этом нет, так вот, одним из главных особенностей XML-комментариев является создание документации прямо из исходных файлов проекта, а так же документация самого кода — классы, процедуры, модули, структуры, функций, их аргументы (параметры).  С помощью синтаксического анализатора (parser’a) можно раскрывать теги XML-комментария, внутри которого, находится дополнительная информация.

Сегодня, мы создадим процедуру, дадим ей описание, описание параметрам и добавим исключение. Когда мы будем вызывать нашу процедуру, IntelliSense будет показывать нам комментарии, которые мы написали.

Для примера будем использовать всего три тега:

  • Тег <summary>, в коде, встречается больше всего, т.к

он описывает элементы (члены) типа, включая методы, свойства и поля

  • Тег <param> описывает параметры метода или свойства. Имеет один атрибут Name = имя параметра
  • Тег <exception> описывает исключения, которые могут произойти. Атрибут cref = название исключения

Весь список тегов:

/// <summary>
/// Моя семья
/// </summary>
/// /// <exception cref="BrotherException">Описание</exception>
/// /// <exception cref="SisterException">Описание</exception>
/// <param name="I">Ваше имя</param>
/// <param name="Mam">Имя вашей мамы</param>
/// <param name="Dad">Имя вышего папы</param>
/// <param name="Sister">Имя вашей сестры</param>
/// <param name="Brother">Имя вашего брата</param>
static void MyFamily(string I, string Mam, string Dad, string Sister, string Brother)
 {
   // процедура
 }
''' <summary>
'''Моя семья
'''</summary>
''' <param name="I">Ваше имя</param>
''' <param name="Mam">Имя вашей мамы</param>
''' <param name="Dad">Имя вышего папы</param>
''' <param name="Sister">Имя вашей сестры</param>
''' <param name="Brother">Имя вашего брата</param>
Sub MyFamily(ByVal I As String, ByVal Mam As String, ByVal Dad As String, ByVal Sister As String, ByVal Brother As String)
    ' процедура
End Sub

Как будет показано в IntelliSense:

Познакомиться с XML-комментариями, тегами и описанием можно на

  • MSDN (VB. NET)
  • Отличная статья про XML-комментарии (C#)





Как закомментировать блок тегов в XML?

Как закомментировать блок тегов в XML?

Т.е. Как я могу закомментировать и все, что внутри него, в приведенном ниже коде?

 <деталь>
    <диапазон>
      <статический текст>
        <элемент отчета x="180" y="0"/>

Я мог бы использовать , но это только для одиночных тегов (как я знаю), например // в Java и C. Я бы хотел что-то более похожее на то, как /** comment **/ можно использовать в Java и C, поэтому я может комментировать более длинные блоки XML-кода.

  • xml
  • комментарии

2

Вы можете использовать этот стиль комментариев в нескольких строках (который существует также в HTML)

 
    <диапазон>

7

Вы можете обернуть текст несуществующей инструкцией по обработке, например:

 

    <статический текст>
      <элемент отчета x="180" y="0"/>
      
    
  
?>

Вложенные инструкции обработки не допускаются, и ‘?>’ завершает инструкцию обработки (см. здесь комментарий заканчивается

Довольно распространенная ошибка. Он унаследован от того, как SGML обрабатывает комментарии. (Прочитайте спецификацию XML в этой теме)

3

На самом деле, вы можете использовать формат с несколькими строками или тегами:

Здесь для комментирования мы должны написать, как показано ниже:

Ярлыки для IntelliJ Idea и Eclipse

Для Windows и Linux:

Ярлык для комментирования одной строки:

Ctrl + /

Ярлык для комментирования нескольких строк:

Ctrl + Shift + /

Для Mac:

Ярлык для комментирования одной строки:

cmnd + /

Ярлык для комментирования нескольких строк:

cmnd + 9000 5 Сдвиг + /

Вы должны помнить одну вещь: вы не можете комментировать атрибут тега XML. Например:

 <текстовое представление
    Android: layout_width = "match_parent"
    android:layout_height="wrap_content"
    
    андроид: textStyle="жирный" />

Здесь TextView — это тег XML, а text — атрибут этого тега. Вы не можете комментировать атрибуты тега XML. Вы должны прокомментировать полный тег XML. Например:

0

Вы можете легко закомментировать данные, используя это:

метод комментирования в xml.

Синтаксис для XML:

напр.

 
   
   <список_классов>
   <студент>
   <имя>
   <класс>A

Правила комментариев XML

 Комментарии не могут появляться перед объявлением XML.
Комментарии могут появляться в любом месте документа.
Комментарии не должны появляться внутри значений атрибутов.
Комментарии не могут быть вложены в другие комментарии.

В Notepad++ вы можете выбрать несколько строк и использовать CTRL+Q, что автоматически сделает блочные комментарии для выбранных строк.

Если вы используете Eclipse IDE, вы можете закомментировать строки в файле XML, выделив их и нажав Ctrl+Shift+c.

XML-комментарий внутри элемента – 1 Ответ
спросил

Изменено
1 год, 5 месяцев назад

Просмотрено
5к раз

Каков альтернативный способ разместить комментарий к атрибутам элемента в следующем XML-коде?

 
  <текстовый вид
        Android: layout_width = "wrap_content"
        android:layout_height="wrap_content"
        android:id="@+id/textView_ben"
        
        android:layout_centerHorizontal="true"/>

1

Комментарий может появляться только до или после начального тега (независимо от того, пустой ли это тег).

Комментарий может , а не появиться в начальном теге XML-элемента:

[40] STag ::= '<' Имя (атрибут S)* S? '>'

Комментарий не может появляться внутри конечного тега:

[44] EmptyElemTag ::= '<' Имя (атрибут S)* S? '/>'

В общем, согласно разделу 2.5 Комментарии :

[Определение: Комментарии могут появляться в любом месте документа за пределами
другая разметка; кроме того, они могут появиться в документе
объявление типа в местах, разрешенных грамматикой. …]

Вот один из способов документирования атрибутов элемента:

В качестве альтернативы такой комментарий может появиться перед тегом; он просто не может оказаться внутри тега.