From 7ec533ee7be3c449e61319fc90bce7e55ee49dfc Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Fri, 5 Apr 2024 22:09:49 +0000 Subject: [PATCH 1/5] Deprecate the missingCodeBlockLanguage warning. --- lib/src/warnings.dart | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index 1aac79d27d..7eef2f7fdc 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -279,15 +279,17 @@ enum PackageWarning implements Comparable { 'deprecated dartdoc usage: {0}', shortHelp: 'A dartdoc directive has a deprecated format.', ), + // TODO(kallentu): Remove this warning. missingCodeBlockLanguage( 'missing-code-block-language', 'missing code block language: {0}', - shortHelp: 'A fenced code block is missing a specified language.', - longHelp: - 'To enable proper syntax highlighting of Markdown code blocks, Dartdoc ' - 'requires code blocks to specify the language used after the initial ' - 'declaration. As an example, to specify Dart you would open the ' - 'Markdown code block with ```dart or ~~~dart.', + shortHelp: '(Deprecated: Use `missing_code_block_language_in_doc_comment` ' + 'lint) A fenced code block is missing a specified language.', + longHelp: '(Deprecated: Use `missing_code_block_language_in_doc_comment` ' + 'lint) To enable proper syntax highlighting of Markdown code blocks, ' + 'Dartdoc requires code blocks to specify the language used after the ' + 'initial declaration. As an example, to specify Dart you would open ' + 'the Markdown code block with ```dart or ~~~dart.', defaultWarningMode: PackageWarningMode.ignore, ); From 68c5fbff7a78e30e69300584fe3ad6b9763b475c Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 8 Apr 2024 19:35:06 +0000 Subject: [PATCH 2/5] Added a stderr warning. --- lib/src/model/documentation_comment.dart | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index ca654903d2..23948e8fec 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -1,3 +1,5 @@ +import 'dart:io'; + import 'package:analyzer/dart/element/element.dart'; import 'package:args/args.dart'; import 'package:crypto/crypto.dart' as crypto; @@ -676,6 +678,8 @@ mixin DocumentationComment for (var element in firstOfPair) { final result = element.group(2)!.trim(); if (result.isEmpty) { + stderr.writeln("The warning 'missingCodeBlockLanguage' is deprecated. " + 'Use the `missing_code_block_language_in_doc_comment` lint instead.'); warn(PackageWarning.missingCodeBlockLanguage, message: 'A fenced code block in Markdown should have a language specified'); From 217bbc69eff3ad4df599bcc39645271ecc736e02 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 8 Apr 2024 19:36:40 +0000 Subject: [PATCH 3/5] Add a copyright msg. --- lib/src/model/documentation_comment.dart | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 23948e8fec..4a3e4d8dc0 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -1,3 +1,7 @@ +// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file +// for details. All rights reserved. Use of this source code is governed by a +// BSD-style license that can be found in the LICENSE file. + import 'dart:io'; import 'package:analyzer/dart/element/element.dart'; From 77a4e3d2f86fa5e3cec4c5c0518b428230139f89 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 8 Apr 2024 20:15:01 +0000 Subject: [PATCH 4/5] Write error on warn and error warnings that are deprecated. --- lib/src/model/documentation_comment.dart | 4 ---- lib/src/warnings.dart | 18 ++++++++++++++++-- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 4a3e4d8dc0..534f83bf72 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -2,8 +2,6 @@ // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. -import 'dart:io'; - import 'package:analyzer/dart/element/element.dart'; import 'package:args/args.dart'; import 'package:crypto/crypto.dart' as crypto; @@ -682,8 +680,6 @@ mixin DocumentationComment for (var element in firstOfPair) { final result = element.group(2)!.trim(); if (result.isEmpty) { - stderr.writeln("The warning 'missingCodeBlockLanguage' is deprecated. " - 'Use the `missing_code_block_language_in_doc_comment` lint instead.'); warn(PackageWarning.missingCodeBlockLanguage, message: 'A fenced code block in Markdown should have a language specified'); diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index 7eef2f7fdc..464a00fdd4 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -291,6 +291,7 @@ enum PackageWarning implements Comparable { 'initial declaration. As an example, to specify Dart you would open ' 'the Markdown code block with ```dart or ~~~dart.', defaultWarningMode: PackageWarningMode.ignore, + isDeprecated: true, ); /// The name which can be used at the command line to enable this warning. @@ -307,6 +308,8 @@ enum PackageWarning implements Comparable { final String _longHelp; + final bool _isDeprecated; + final PackageWarningMode _defaultWarningMode; const PackageWarning( @@ -316,11 +319,13 @@ enum PackageWarning implements Comparable { String longHelp = '', String warnablePrefix = 'from', String referredFromPrefix = 'referred to by', + bool isDeprecated = false, PackageWarningMode defaultWarningMode = PackageWarningMode.warn, }) : _shortHelp = shortHelp, _longHelp = longHelp, _warnablePrefix = warnablePrefix, _referredFromPrefix = referredFromPrefix, + _isDeprecated = isDeprecated, _defaultWarningMode = defaultWarningMode; static PackageWarning? _byName(String name) => @@ -404,6 +409,7 @@ class PackageWarningOptions { for (var warningName in errorsForDir) { var packageWarning = PackageWarning._byName(warningName); if (packageWarning != null) { + newOptions.writeErrorOnDeprecation(packageWarning); newOptions.error(packageWarning); } } @@ -412,6 +418,7 @@ class PackageWarningOptions { for (var warningName in warningsForDir) { var packageWarning = PackageWarning._byName(warningName); if (packageWarning != null) { + newOptions.writeErrorOnDeprecation(packageWarning); newOptions.warn(packageWarning); } } @@ -457,14 +464,21 @@ class PackageWarningOptions { return newOptions; } + void error(PackageWarning kind) => + warningModes[kind] = PackageWarningMode.error; + void ignore(PackageWarning kind) => warningModes[kind] = PackageWarningMode.ignore; void warn(PackageWarning kind) => warningModes[kind] = PackageWarningMode.warn; - void error(PackageWarning kind) => - warningModes[kind] = PackageWarningMode.error; + void writeErrorOnDeprecation(PackageWarning warning) { + if (warning._isDeprecated) { + stderr.writeln("The warning 'missingCodeBlockLanguage' is deprecated. " + 'Use the `missing_code_block_language_in_doc_comment` lint instead.'); + } + } PackageWarningMode getMode(PackageWarning kind) => warningModes[kind]!; } From 32459eb8c3129e628298e297d18cc048f1af0203 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Mon, 8 Apr 2024 20:22:53 +0000 Subject: [PATCH 5/5] Generalize warning oops. --- lib/src/warnings.dart | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index 464a00fdd4..7fe99aecd3 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -475,8 +475,7 @@ class PackageWarningOptions { void writeErrorOnDeprecation(PackageWarning warning) { if (warning._isDeprecated) { - stderr.writeln("The warning 'missingCodeBlockLanguage' is deprecated. " - 'Use the `missing_code_block_language_in_doc_comment` lint instead.'); + stderr.writeln("The warning '${warning._flagName}' is deprecated."); } }