Dart поддерживает однострочные комментарии, многострочные комментарии и комментарии к документации.
Однострочные комментарии
Однострочный комментарий начинается с //. Все между // и концом строки игнорируется компилятором Dart
void main() {
// TODO: refactor into an AbstractLlamaGreetingFactory?
print('Welcome to my Llama farm!');
}Многострочные комментарии
Многострочный комментарий начинается с /* и заканчивается */. Все между /* и */ игнорируется компилятором Dart (если комментарий не является комментарием к документации; см. Следующий раздел). Многострочные комментарии могут быть вложенными
void main() {
/*
* This is a lot of work. Consider raising chickens.
Llama larry = Llama();
larry.feed();
larry.exercise();
larry.clean();
*/
}Комментарии к документации
Комментарии к документации — это многострочные или однострочные комментарии, начинающиеся с /// или /**. Использование /// в последовательных строках имеет тот же эффект, что и многострочный комментарий к документу.
Внутри комментария к документации компилятор Dart игнорирует весь текст, если он не заключен в квадратные скобки. Используя скобки, вы можете ссылаться на классы, методы, поля, переменные верхнего уровня, функции и параметры. Имена в скобках разрешаются в лексической области документированного программного элемента.
Вот пример комментариев документации со ссылками на другие классы и аргументы:
/// A domesticated South American camelid (Lama glama).
///
/// Andean cultures have used llamas as meat and pack
/// animals since pre-Hispanic times.
class Llama {
String name;
/// Feeds your llama [Food].
///
/// The typical llama eats one bale of hay per week.
void feed(Food food) {
// ...
}
/// Exercises your llama with an [activity] for
/// [timeLimit] minutes.
void exercise(Activity activity, int timeLimit) {
// ...
}
}В сгенерированной документации [Food] становится ссылкой на документы API для класса Food.
Для анализа кода Dart и генерации HTML-документации вы можете использовать инструмент генерации документации SDK. Пример сгенерированной документации см. В документации по Dart API. Для получения советов о том, как структурировать ваши комментарии, см. Рекомендации для комментариев Dart Doc.
