diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index ca654903d2..534f83bf72 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 'package:analyzer/dart/element/element.dart'; import 'package:args/args.dart'; import 'package:crypto/crypto.dart' as crypto; diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index 1aac79d27d..7fe99aecd3 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -279,16 +279,19 @@ 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, + isDeprecated: true, ); /// The name which can be used at the command line to enable this warning. @@ -305,6 +308,8 @@ enum PackageWarning implements Comparable { final String _longHelp; + final bool _isDeprecated; + final PackageWarningMode _defaultWarningMode; const PackageWarning( @@ -314,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) => @@ -402,6 +409,7 @@ class PackageWarningOptions { for (var warningName in errorsForDir) { var packageWarning = PackageWarning._byName(warningName); if (packageWarning != null) { + newOptions.writeErrorOnDeprecation(packageWarning); newOptions.error(packageWarning); } } @@ -410,6 +418,7 @@ class PackageWarningOptions { for (var warningName in warningsForDir) { var packageWarning = PackageWarning._byName(warningName); if (packageWarning != null) { + newOptions.writeErrorOnDeprecation(packageWarning); newOptions.warn(packageWarning); } } @@ -455,14 +464,20 @@ 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 '${warning._flagName}' is deprecated."); + } + } PackageWarningMode getMode(PackageWarning kind) => warningModes[kind]!; }