Комментарии Dart

Язык Dart поддерживает всего три вида комментариев: однострочные комментарии, многострочные комментарии, документационные комментарии; компилятор игнорирует обычный текст внутри комментариев, только документационные комментарии подходят для генерации документации к коду.

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

Документационные комментарии позволяют с помощью специальных инструментов генерировать справочную документацию по API. Это удобно как для собственного ознакомления с кодом, так и для других разработчиков, использующих вашу библиотеку.

Если вы изучали другие языки программирования, вы быстро освоите комментарии Dart. Синтаксис почти совпадает с C, C++, Java, C# и другими языками семейства C.

1. Однострочный комментарий //

1. Начинается с символа //;
2. Всё содержимое от // до конца текущей строки игнорируется компилятором Dart;
3. Действует только для одной строки, не поддерживает перенос на несколько строк.

Пример кода

void main() {
  // TODO: Рефакторить в абстрактную фабрику приветствий для лам
  print('Добро пожаловать на мою ферму лам!');
}
Code language: JavaScript (javascript)

2. Многострочный комментарий /* */

1. Начальный маркер /*, конечный маркер */;
2. Любой текст между /* и */ игнорируется компилятором (кроме документационных комментариев, см. ниже);
3. Поддерживает вложенность.

Пример кода

void main() {
  /*
   * Разведение лам требует много труда, можно подумать о разведении кур.

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Code language: Dart (dart)

В коде выше весь фрагмент внутри фигурных скобок закомментирован, он не компилируется и полностью игнорируется компилятором.

3. Документационные комментарии

Используются для генерации официальной документации API. При работе с вашей библиотекой другие разработчики могут по ней изучать описания классов, функций, параметров и правила использования, как по инструкции.

1. Два варианта написания

• Однострочный документационный комментарий: несколько последовательных строк с ///, работает аналогично многострочному документационному комментарию. Обратите внимание, что используется три слэша.
• Многострочный документационный комментарий: начинается с /**, заканчивается на */. В начале дополнительная звёздочка.

2. Основные синтаксические правила

1. Обычный текст внутри документационного комментария игнорируется анализатором кода;
2. Специальная синтаксическая конструкция: идентификатор в квадратных скобках [] позволяет ссылаться на классы, методы, поля, глобальные переменные, функции и параметры;
3. Имена в скобках разрешаются в лексической области видимости комментируемого кода;
4. После генерации документации конструкция [идентификатор] автоматически превращается в гиперссылку на соответствующий раздел документации.

Пример кода

// Обычный однострочный комментарий: определение класса корма
class Food {
  String type;
  // Однострочный комментарий: количество тюков корма
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
Обычный многострочный комментарий:
Перечисление видов активности для метода движения лам
Демонстрация вложенных комментариев
/* Внутренний вложенный комментарий */
*/
enum Activity {
  walk,
  run,
  graze
}

/// Одомашненное южноамериканское верблюдовое животное (лама, научное название Lama glama)
///
/// Ещё до открытия Америки андийские цивилизации использовали лам как источник мяса и тягловую силу.
///
/// Как и другие животные, ламам нужен корм: передавайте корм типа [Food] и вызывайте метод [feed].
class Llama {
  String? name;

  /// Кормить ламу указанным кормом [food]
  ///
  /// Одна лама обычно съедает один тюк сена в неделю.
  void feed(Food food) {
    // Однострочный комментарий: вывод информации о кормлении
    print("${name} съела ${food.baleCount} тюк(а) ${food.type}");
  }

  /// Заставить ламу выполнять активность [activity] в течение [timeLimit] минут
  void exercise(Activity activity, int timeLimit) {
    print("${name} занимается ${activity.name} ${timeLimit} минут");
  }
}

void main() {
  // TODO: В дальнейшем расширить функционал для управления несколькими ламами
  Llama larry = Llama();
  larry.name = "Ларри";

  // Создать корм из сена
  Food hay = Food("сено", 1);
  larry.feed(hay);

  // Прогулка ламы 20 минут
  larry.exercise(Activity.walk, 20);
}
Code language: PHP (php)

После генерации документации: [feed] ведёт к разделу с описанием метода feed текущего класса, [Food] — к документации класса Food.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
Ларри съела 1 тюк сена
Ларри занимается walk 20 минут

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiCode language: JavaScript (javascript)

После запуска в корне проекта появляется папка doc, при открытии вы увидите сгенерированную документацию

Сопутствующие инструменты

1. Генератор документации: dart doc Назначение: парсит исходный код Dart и автоматически создаёт документацию API в формате HTML. Официальная документация Dart также создаётся этим инструментом.
2. Руководство по стилю комментариев: официальный гайд «Effective Dart: Documentation», содержит стандартные структуры и правила оформления комментариев.

Итог

Сравнительная таблица

Тип комментария	Начальный символ	Многострочный	Вложенность	Назначение
Однострочный	//	Нет, только одна строка	Не поддерживается	Краткие пометки, задачи TODO в коде
Обычный многострочный	/* */	Да, любое количество строк	Поддерживается	Массовое закомментирование больших блоков кода, длинные описания
Документационный	/// / /** */	Да	Не рекомендуется	Описание API классов/методов/переменных, генерация официальной документации, ссылки на идентификаторы через []