Как прокомментировать одну строку в XML? Комментарий в xml
Комментарии в Android Layout xml
Как и другие, комментарий в XML выглядит следующим образом:
<!-- this is a comment -->Обратите внимание, что они могут охватывать несколько строк
<!-- This is a comment on multiple lines -->Но они не могут быть вложенными
<!-- This <!-- is a comment --> This is not -->Также вы не можете использовать их внутри тегов
<EditText <!--This is not valid--> android:layout_width="fill_parent" />Комментарии XML начинаются с <!-- и заканчиваются на --> .
Например:
<!-- This is a comment. -->Есть два способа сделать это:
Начните свой комментарий с "<!--" затем закончите свой комментарий с помощью " -->"
Пример <!-- my comment goes here -->
Выделите часть, которую вы хотите прокомментировать, и нажмите CTRL + SHIFT + /
Комментарии ВНУТРИ метки доступны
Возможно создание пользовательских атрибутов, которые могут использоваться для комментирования / документирования.
В приведенном ниже примере определяется атрибут documentation:info с примерным значением комментария:
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:documentation="documentation.mycompany.com" android:layout_width="match_parent" android:layout_height="match_parent" android:id="@+id/relLayoutID" documentation:info="This is an example comment" > <TextView documentation:purpose="Instructions label" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Click here to begin." android:id="@+id/tvMyLabel" android:layout_alignParentTop="true" android:layout_alignParentStart="true" documentation:info="Another example comment" documentation:translation_notes="This control should use the fewest characters possible, as space is limited" /> </RelativeLayout>Обратите внимание, что в этом случае documentation.mycompany.com - это просто определение для нового пользовательского пространства имен XML ( documentation ) и, таким образом, представляет собой уникальную строку URI - это может быть что угодно, пока оно уникально. documentation справа от xmlns: также может быть любой - это работает так же, как и используется пространство имен android: XML.
Используя этот формат, можно создать любое количество атрибутов, таких как documentation:info , documentation:translation_notes и т. Д., А также значение описания, причем формат совпадает с любым атрибутом XML.
В итоге:
- Добавьте xmls:my_new_namespace в корневой (верхний уровень) XML-элемент в файле макета XML. Установите его значение в уникальную строку
- Под любым дочерним элементом XML в файле используйте новое пространство имен и любое слово, следующее для определения тегов комментариев, которые игнорируются при компиляции, например <TextView my_new_namespace:my_new_doc_property="description" />
вы также можете добавить комментарий, нажав Ctrl + shift + / и сдвинуть + / для одной строки.
code-examples.net
android - Комментарии в Android Layout xml
Комментарии Возможны теги INSIDE
Возможно создание пользовательских атрибутов, которые могут использоваться для комментариев/документации.
В приведенном ниже примере определяется атрибут documentation:info с примерным значением комментария:
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:documentation="documentation.mycompany.com" android:layout_width="match_parent" android:layout_height="match_parent" android:id="@+id/relLayoutID" documentation:info="This is an example comment" > <TextView documentation:purpose="Instructions label" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Click here to begin." android:id="@+id/tvMyLabel" android:layout_alignParentTop="true" android:layout_alignParentStart="true" documentation:info="Another example comment" documentation:translation_notes="This control should use the fewest characters possible, as space is limited" /> </RelativeLayout>Обратите внимание, что в этом случае documentation.mycompany.com является просто определением для нового пользовательского пространства имен XML (documentation) и, таким образом, просто уникальный URI string - это может быть что угодно, пока оно уникально. documentation справа от xmlns: также может быть любым - это работает так же, как и используется пространство имен android: XML.
Используя этот формат, можно создать любое количество атрибутов, например documentation:info, documentation:translation_notes и т.д., а также значение описания, формат которого совпадает с любым атрибутом XML.
Вкратце:
- Добавить атрибут xmls:my_new_namespace в XML файл корневого (верхнего уровня) XML в файле макета XML. Установите его значение в уникальную строку
- Под любым дочерним XML-элементом внутри файла используйте новое пространство имен и любое слово, следующее для определения тегов комментариев, которые игнорируются при компиляции, например. <TextView my_new_namespace:my_new_doc_property="description" />
qaru.site
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
Познакомиться с XML-комментариями, тегами и описанием можно на
Похожие записи:
ds-release.ru
Комментарии в Android Layout xml Oh! Android
Я хотел бы ввести некоторые комментарии в XML-файлы макета, как бы я это сделал?
Как и другие, комментарий в XML выглядит следующим образом:
<!-- this is a comment -->Обратите внимание, что они могут охватывать несколько строк
<!-- This is a comment on multiple lines -->Но они не могут быть вложенными
<!-- This <!-- is a comment --> This is not -->Также вы не можете использовать их внутри тегов
<EditText <!--This is not valid--> android:layout_width="fill_parent" />Консорциум World Wide Web (W3C) фактически определил интерфейс комментариев. В определении говорится, что all the characters between the starting ' <!--' and ending '-->' form a part of comment content and no lexical check is done on the content of a comment .
Более подробная информация доступна на сайте developer.android.com .
Таким образом, вы можете просто добавить свой комментарий между любыми начальными и конечными тегами. В Eclipse IDE просто набрав <!-- будет автоматически заполнять комментарий для вас. Затем вы можете добавить текст комментария между ними.
Например:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools" android:layout_width="fill_parent" android:layout_height="fill_parent" android:orientation="vertical" tools:context=".TicTacToe" > <!-- This is a comment --> </LinearLayout>Цель особого упоминания заключается в том, что вы не можете использовать его внутри тега.
Например:
<TextView android:text="@string/game_title" <!-- This is a comment --> android:layout_height="wrap_content" android:layout_width="fill_parent"/>Неверно и даст следующую ошибку
Element type "TextView" must be followed by either attribute specifications, ">" or "/>".Комментарии XML начинаются с <!-- и заканчиваются на --> .
Например:
<!-- This is a comment. -->Комментарии INSIDE теги возможны
Можно создавать пользовательские атрибуты, которые могут использоваться для целей комментирования / документации.
В приведенном ниже примере определяется атрибут documentation:info с примерным значением комментария:
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:documentation="documentation.mycompany.com" android:layout_width="match_parent" android:layout_height="match_parent" android:id="@+id/relLayoutID" documentation:info="This is an example comment" > <TextView documentation:purpose="Instructions label" android:layout_width="wrap_content" android:layout_height="wrap_content" android:text="Click here to begin." android:id="@+id/tvMyLabel" android:layout_alignParentTop="true" android:layout_alignParentStart="true" documentation:info="Another example comment" documentation:translation_notes="This control should use the fewest characters possible, as space is limited" /> </RelativeLayout>Обратите внимание, что в этом случае documentation.mycompany.com – это просто определение для нового пользовательского пространства имен XML ( documentation ), и, таким образом, это просто уникальная строка URI – это может быть все до тех пор, пока оно уникально. documentation справа от xmlns: также может быть что угодно – это работает так же, как и используется пространство имен android: XML.
Используя этот формат, можно создать любое количество атрибутов, таких как documentation:info , documentation:translation_notes и т. Д., А также значение описания, причем формат совпадает с любым атрибутом XML.
В итоге:
- Добавьте xmls:my_new_namespace в корневой (верхний уровень) XML-элемент в файле макета XML. Установите его значение в уникальную строку
- Под любым дочерним элементом XML внутри файла используйте новое пространство имен и любое слово, следующее для определения тегов комментариев, которые игнорируются при компиляции, например <TextView my_new_namespace:my_new_doc_property="description" />
Если вы хотите прокомментировать в Android Studio . Просто нажмите ctrl + / .
Из примечания Федерико Куллоки:
Также вы не можете использовать их внутри тегов
Означает; Вы должны поместить комментарий в верхнюю или нижнюю часть файла – все места, в которые вы действительно хотите добавить комментарии, по крайней мере находятся внутри тега макета верхнего уровня
www.ohandroid.com
Рекомендуется использовать XML-теги для комментариев документации (Visual Basic)
- 07/20/2015
- Время чтения: 2 мин
-
Соавторы
В этой статье
Компилятор Visual Basic может обработать комментарии документации в коде в XML-файл.The Visual Basic compiler can process documentation comments in your code to an XML file. Дополнительные средства можно использовать для обработки XML-файла в документации.You can use additional tools to process the XML file into documentation.
Комментарии XML разрешены в конструкциях кода, таких как типы и члены типов.XML comments are allowed on code constructs such as types and type members. Для разделяемых типов только одна часть типа может содержать комментарии XML, несмотря на то, что нет никаких ограничений на комментирование его членов.For partial types, only one part of the type can have XML comments, although there is no restriction on commenting its members.
Примечание
Комментарии документации не может применяться к пространствам имен.Documentation comments cannot be applied to namespaces. Причина заключается в одно пространство имен может охватывать несколько сборок, что не все сборки должны загружаться в то же время.The reason is that one namespace can span several assemblies, and not all assemblies have to be loaded at the same time.
Компилятор обрабатывает любой тег, допустимый XML-код.The compiler processes any tag that is valid XML. Следующие теги предоставляют часто используемые возможности в документации для пользователей.The following tags provide commonly used functionality in user documentation.
(1 компилятор проверяет синтаксис.)(1 The compiler verifies syntax.)
Примечание
В текст комментария документации угловые скобки, используйте < и >.If you want angle brackets to appear in the text of a documentation comment, use < and >. Например, строка "<text in angle brackets>" будет отображаться как <text in angle brackets>.For example, the string "<text in angle brackets>" will appear as <text in angle brackets>.
См. такжеSee Also
Документирование кода с помощью XMLDocumenting Your Code with XML/doc/docПрактическое руководство. Создание XML-документацииHow to: Create XML Documentation
docs.microsoft.com
xml - Как прокомментировать одну строку в XML?
Как говорили другие, нет способа сделать в XML один комментарий строки юридически, который комментирует несколько строк, но есть способы упростить комментирование сегментов XML. Посмотрев пример ниже, если вы добавите ' > ' в строку 1, XmlTag будет раскован. Удалите ' > ', и он снова закомментировал. Это самый простой способ, с помощью которого я быстро комментировал/раскомментировал XML, не нарушая его.
<!-- -- <XmlTag variable="0" /> <!-- -->Дополнительным преимуществом является то, что вы обрабатываете только верхний комментарий, а нижний комментарий может просто сидеть там навсегда. Это нарушает совместимость с SGML, и некоторые синтаксические анализаторы XML будут работать на нем. Пока это не постоянное крепление в вашем XML, и ваши парсеры принимают его, это не проблема. StackOverflow и Notepad ++ синтаксис highlighter рассматривают его как многострочный комментарий, библиотека ускорения С++ рассматривает его как многострочный комментарий, и единственный парсер, который я нашел до сих пор, который разрывает тот, который находится в .Net, а именно С#. Поэтому сначала убедитесь, что ваши инструменты, IDE, библиотеки, язык и т.д. Принимают его перед использованием.
Если вам нужна совместимость SGML, просто используйте это вместо:
<!-- - <XmlTag variable="0" /> <!- -->Добавьте '- > ' в верхний комментарий и '-' в нижний комментарий. Нижняя сторона должна каждый раз редактировать нижний комментарий, что, вероятно, облегчит просто вводить <!-- вверху и --> внизу каждый раз.
Я также хочу упомянуть, что другие комментаторы рекомендуют использовать XML-редактор, который позволяет вам щелкнуть правой кнопкой мыши и комментировать/раскомментировать блоки XML, что, вероятно, предпочтительнее, чем приманки для поиска/замены трюков (это также послужило бы хорошим ответом сам по себе, но я никогда не использовал такие инструменты. Я просто хочу, чтобы информация не терялась с течением времени). Мне лично никогда не приходилось разбираться с XML достаточно, чтобы оправдать, что редактор стал более интересным, чем Notepad ++, так что это полностью зависит от вас.
qaru.site
FAQ по документирующим комментариям в C#
Автор: Anson HortonПеревод: Никита Зимин«Деловые программы»Источник: C# XML documentation comments FAQ
Опубликовано: 14.09.2006Исправлено: 19.09.2006Версия текста: 1.0С тех пор как мы выпустили самую первую версию C# 1.0, я получаю один-два вопроса в месяц о документирующих XML-комментариях. Для краткости такие комментарии часто называют «doc comments». Диапазон вопросов — от использования XML-комментариев в Visual Studio до рекомендуемой XML-схемы. Этот пост рассматривает несколько общих вопросов из тех, что я видел.
Почему нет многострочного варианта XML-комментариев?
На самом деле, есть две формы документирующих комментариев в C#, одно- и многострочная. Однако однострочная версия используется намного чаще, фактически, многострочная версия не поддерживалась до компилятора версии 1.1, хотя она и была определена в спецификации языка на версию 1.0. Однострочная версия, по-видимому, привычна любому пользователю Visual Studio, синтаксическим признаком является тройной слэш в начале строки (///):
| static void Example() { } |
Многострочная версия использует /**:
| static void Example() { } |
Обе версии функционально идентичны, единственное различие состоит в том, что многострочную версию можно использовать прямо в строке («inline»), внутри выражений.
Сервис языка C# не поддерживает многострочные XML-комментарии настолько, насколько это сделано для однострочных комментариев (т.е., при вводе /** не происходит автоматической генерации тэгов), однако, подсветка многострочных документирующих комментариев работает, и в VS2005 есть возможность получения списка завершения для тэгов, но вы должны сначала закрыть многострочный комментарий, а затем вернуться назад, чтобы вводить тэги.
Как мне сделать так, чтобы VS показывала текст XML-комментариев на типы и методы моих компонентов в списках завершения и в браузере объектов?
Довольно долгое время этот вопрос был наиболее частым. И краткий, и полный ответ состоит в том, что вы должны распространять XML-файл, созданный компилятором, вместе с компонентом. Они должны лежать в одном и том же каталоге, и имя XML-файла должно совпадать с именем компонента, за исключением расширения «.xml». Для демонстрации этого я написал руководство, содержащее последовательность действий (для VS2003), оно доступно здесь.
Как в документирующих XML-комментариях ссылаться на дженерик-типы (generic types)?
Некоторые из тэгов, рекомендованных для C#, имеют атрибут с именем «cref», означающий «code reference». Этот атрибут может использоваться инструментами для создания ссылок между различными типами и членами (например, браузер объектов использует cref-ы для создания гиперссылок, позволяющих быстро переходить к связанному типу). На самом деле, компилятор C# до некоторой степени понимает cref. Компилятор пытается связать тип или член, указанный в атрибуте cref, с элементом кода, определяющим источник. В случае, когда это удается, этот тип/член полностью называется в генерируемом XML-файле. Например:
| using System.Collections; class Program { void DoSomething(ArrayList al) { } } |
Это преобразуется в следующий фрагмент XML-файла:
| <member name="M:Program.DoSomething(System.Collections.ArrayList)"> <summary> DoSomething takes a <see cref="T:System.Collections.ArrayList"/> </summary> </member> |
Обратите внимание, что компилятор связал ArrayList и подставил вместо него System.Collections.ArrayList.
Я уверен, вы говорите — «ух ты, отлично... но что нам это дает в плане дженериков?» Хороший вопрос. Дженерики усложняют документирующие комментарии, потому что C# использует угловые скобки, которые обычно обозначают тэги XML. Есть возможность использовать обычный механизм экранирования угловых скобок в XML (< >). К сожалению, при этом текст выглядит довольно уродливо:
| using System.Collections.Generic; class Program { void DoSomething(List<int> al) { } } |
Этот способ может стать довольно обременительным в случае, когда дженерик-тип имеет множество аргументов. Команда разработки компилятора решила эту проблему, разрешив использование альтернативного синтаксиса для ссылок на дженерик-типы и их методы в документирующих комментариях. А именно, вместо использования открывающих и закрывающих угловых скобок, допустимо использовать открывающие и закрывающие фигурные скобки:
| using System.Collections.Generic; class Program { void DoSomething(List<int> al) { } } |
Компилятор понимает такой синтаксис и корректно заменит List{T} на System.Collections.Generic.List<T>.
Если используется тэг <example>, в котором показан пример со множеством дженерик-типов и методов, то более простым способом будет окружить пример блоком CDATA. В этом случае нет необходимости в экранировании угловых скобок.
Какие тэги документирующих комментариев понимаются и используются Visual Studio?
Набор тэгов, которые Visual Studio использует для обработки и представления информации:
| summary | Completion lists, quick info, class view, class designer, object browser, object test bench |
| param | Parameter help, quick info, object test bench, class designer, object browser |
| exception | Completion lists, quick info, object browser |
| include | Компилятор C# |
| returns | Object browser |
| see/seealso | Object browser |
Функция «метаданные в качестве исходного кода» («metadata as a source»), которая применяется при выполнении команды Go To Definition с переходом на тип или член класса, определенный в метаданных, обрабатывает ряд тэгов, определенных в спецификации C# и пытается с их использованием представить метаданные в приемлемом виде.
Как из XML-файла получить документацию в формате HTML или .chm?
На самом деле, генерируемый XML не содержит достаточно информации для полной генерации хорошей документации. Фактически, прямой целью было лишь создание XML-файла, содержащего информацию, достаточную для комментирования элементов кода, представленных в метаданных. Тем не менее, есть ряд инструментов, принимающих на входе сборку и XML-файл, и генерирующих красивый и удобный для изучения документ. NDoc был излюбленным средством, по словам многих разработчиков, с которыми я говорил, но я вижу, что разработка NDoc довольно замедлилась. Другим вариантом является использование SandCastle.
Любой из материалов, опубликованных на этом сервере, не может быть воспроизведен в какой бы то ни было форме и какими бы то ни было средствами без письменного разрешения владельцев авторских прав.
rsdn.org
