Комментарий в 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-документации во время компиляции.
Поместите текстовый курсор над элементом, например методом, который нужно задокументировать.
Выполните одно из следующих действий.
Введите
///
в C# или'''
в Visual BasicВ меню Правка выберите IntelliSense>Вставить комментарий.
Щелкните правой кнопкой мыши или вызовите контекстное меню в редакторе кода или над ним и выберите Фрагмент кода>Вставить комментарий.
Над элементом кода сразу же создается XML-шаблон. Например, при комментировании метода он создает <элемент сводки>, <элемент param> для каждого параметра и возвращаемый<> элемент для документирования возвращаемого значения.
Введите описание для каждого 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 Комментарии :
[Определение: Комментарии могут появляться в любом месте документа за пределами
другая разметка; кроме того, они могут появиться в документе
объявление типа в местах, разрешенных грамматикой. …]
Вот один из способов документирования атрибутов элемента:
В качестве альтернативы такой комментарий может появиться перед тегом; он просто не может оказаться внутри тега.