02.12.2024 18:07
alexeyinkin 0 942 Источник

Новшества Dart 3.4 разобраны в официальном анонсе здесь. Но там не говорится про два новых правила линтера.

missing_code_block_language_in_doc_comment

Это правило для улучшения документации.

Комментарии с документацией в Dart могут содержать примеры кода в тройных обратных кавычках (синтаксис Markdown). Вот пример из кода Flutter:

Это генерирует красивую документацию:

Обратите внимание на подсветку кода. Она сделана, потому что генератор документации видит подсказку с языком: ```dart

Генератор поддерживает и другие языки. Вот пример с JSON:

И сгенерированная из него документация:

Если пропустить язык, то раньше генератор выдавал предупреждение. Теперь вместо этого — линт.

Используйте ```none, если хотите не подсвечивать код.

unnecessary_library_name

Это правило — для чистки устаревших вещей.

Библиотекой называется любой файл Dart, кроме тех, которые включаются через ключевое слово part. Также есть ключевое слово library с долгой историей. Давным‑давно, когда на Земле господствовали титаны, файлы начинались с ключевого слова library и названия библиотеки. После этого можно было объявлять другие файлы частью этой библиотеки, чтобы они видели приватные идентификаторы друг друга:

library my_library;

part 'my_part.dart';

int _privateValue = 1;

Нужна была такая директива part в главном файле и вот такая part of в подключаемом:

part of my_library; // Используем название библиотеки.

int get value => _privateValue;

Поскольку подключаемый файл не упоминал путь к главному файлу, это создавало кучу проблем с поиском, и это уже давно deprecated. Для подключения файлов мы уже давно используем путь к главному файлу:

// Главный файл больше не начинается с названия библиотеки.

part 'my_part.dart';

int _privateValue = 1;
part of 'my_library.dart'; // Путь к главному файлу вместо названия библиотеки.

int get value => _privateValue;

Директива library всё ещё существует. У неё осталось только одно применение — навешивать аннотации на весь файл. Начиная с Dart 3.0, мы можем отбросить название и оставить только ключевое слово library:

@Deprecated('Do not use anything in this library.')
library;

Однако, название технически всё ещё можно указать:

@Deprecated('Do not use anything in this library.')
library my_library;

Бесполезный идентификатор — это всегда плохо. К тому же, если он неуникальный, будут проблемы. Теперь можно форсировать отказ от старого синтаксиса part of там, где он ещё остался. Вот для этого сделано новое правило линтера. Оно будет ругаться на библиотеки с именами и заставит вас переписать старые директивы part of.

Более старые линты

Если вы пропустили мои предыдущие статьи, то вот:

Как подключить новые линты

Прочитайте эту статью о том, как подключить эти правила вручную.

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

Не пропускайте мои статьи, добавляйтесь в Телеграм‑канал: ainkin_com
Русские переводы реже и с задержкой здесь: ainkin_com_ru

(Оригинал опубликован в канале на английском, когда Dart 3.4 только вышел.)

Комментарии (0)