ASDoc in MXML. Правильно комментируем MXML.

MXML для Flex-разработки имеет первостепенное значение. Однако, воспринимая его как порождение XML, до некоторых пор, я не считал его языком программирования или чем-то в этом духе.
Теперь, уже достаточно сроднившись с MXML, понимаю, что есть необходимость правильно его комментировать. Просматривая листинги MXML, глаз так же нуждается в разделении блоков, как и при чтении AS-кода.
Если с AS-кодом всё давно ясно (я его использую везде где надо и где необязательно), то вот с MXML хотелось бы разобраться. И поможет нам в этом статейка "ASDoc in MXML - Functional and Design Specification". Выделим основные мысли из нее.

Основные положения

В настоящее время не существует способа документировать MXML-компоненты. (Кстати, в лайфдоках про это вот что сказано: Documenting MXML files). Компилятор asdoc не обрабатывает комментарии в MXML-файлах. Но число компонентов, разрабатываемых на базе MXML неуклонно растет, поэтому поддержка в asdoc файлов MXML очень бы помогла разработчикам при создании документации.

ASDoc комментарий

Для того, чтобы ASDoc-комментарий был обработан asdoc-компилятором, необходимо указать 3 тире после <!:
<!--- asdoc comment -->
Для сравнения - обычный комментарий начинается с 2-х тире.

Комментирование MXML-компонентов и компонента уровня класса

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

<?xml version="1.0"?>

<!-- Standard MXML comment: events\myComponents\MyButton.mxml -->

<!---
The class level comment for the component.
This tag supports all ASDoc tags, and does not require a CDATA block.

@see mx.container.VBox
-->
<mx:VBox xmlns="http://ns.adobe.com/mxml/2009" xmlns:mx="library:adobe/flex/halo" >

<!--- Comment for button -->
<mx:Button id="myButton" label="This button has comment"/>

<!--- This comment doesn't belong to any component and will be ignored -->

</mx:VBox>

Комментарии перед тегами Script, Metadata будут игнорироваться. Перед тегами Definition, Library, Private и внутри их, комментарии так же будут игнорироваться.

Итог

В статье приводятся примеры использования ASDoc комментирования в различных его применениях. Рассматривать их подробно я не буду - всё достаточно прозрачно.

Вывод таков - MXML комментировать надо. И для этого уже существует прототип (если я правильно понял) стандарта, которого и следует придерживаться.