blob: 272887eb664fd5852eb0e520d9ac18cd55bc2a70 [file] [log] [blame]
// Copyright (c) 2017, 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:collection';
import 'package:analyzer/dart/element/element.dart';
import 'package:analyzer/file_system/file_system.dart';
import 'package:dartdoc/src/dartdoc_options.dart';
import 'package:dartdoc/src/logging.dart';
import 'package:dartdoc/src/model/comment_referable.dart';
import 'package:dartdoc/src/model/model.dart';
import 'package:dartdoc/src/package_meta.dart';
const _namePlaceholder = '@@name@@';
mixin PackageWarningOptionContext implements DartdocOptionContextBase {
bool get allowNonLocalWarnings =>
// allowWarningsInPackages, ignoreWarningsInPackages, errors, warnings, and
// ignore are only used indirectly via the synthetic packageWarningOptions
// option.
PackageWarningOptions get packageWarningOptions =>
bool get verboseWarnings => optionSet['verboseWarnings'].valueAt(context);
List<DartdocOption<Object?>> createPackageWarningOptions(
PackageMetaProvider packageMetaProvider,
) {
var resourceProvider = packageMetaProvider.resourceProvider;
return [
DartdocOptionArgOnly<bool>('allowNonLocalWarnings', false, resourceProvider,
negatable: true,
help: 'Show warnings from packages we are not documenting locally.'),
// Options for globally enabling/disabling all warnings and errors
// for individual packages are command-line only. This will allow
// meta-packages like Flutter to control whether warnings are displayed for
// packages they don't control.
'allowWarningsInPackages', null, resourceProvider,
splitCommas: true,
'Package names to display warnings for (ignore all others if set)'),
'allowErrorsInPackages', null, resourceProvider,
splitCommas: true,
help: 'Package names to display errors for (ignore all others if set)'),
'ignoreWarningsInPackages', null, resourceProvider,
splitCommas: true,
help: 'Package names to ignore warnings for. Takes priority over '
'ignoreErrorsInPackages', null, resourceProvider,
splitCommas: true,
help: 'Package names to ignore errors for. Takes priority over '
// Options for globally enabling/disabling warnings and errors across
// packages. Loaded from dartdoc_options.yaml, but command line arguments
// will override.
DartdocOptionArgFile<List<String>?>('errors', null, resourceProvider,
splitCommas: true,
'Additional warning names to force as errors. Specify an empty list to force defaults (overriding dartdoc_options.yaml)\nDefaults:\n${_warningsListHelpText(PackageWarningMode.error)}'),
DartdocOptionArgFile<List<String>?>('ignore', null, resourceProvider,
splitCommas: true,
'Additional warning names to ignore. Specify an empty list to force defaults (overriding dartdoc_options.yaml).\nDefaults:\n${_warningsListHelpText(PackageWarningMode.ignore)}'),
DartdocOptionArgFile<List<String>?>('warnings', null, resourceProvider,
splitCommas: true,
'Additional warning names to show as warnings (instead of error or ignore, if not warning by default).\nDefaults:\n${_warningsListHelpText(PackageWarningMode.warn)}'),
// Synthetic option uses a factory to build a PackageWarningOptions from all the above flags.
(DartdocSyntheticOption<PackageWarningOptions> option, Folder dir) =>
PackageWarningOptions.fromOptions(option, dir, packageMetaProvider),
String _warningsListHelpText(PackageWarningMode mode) {
return (packageWarningDefinitions.values
.where((d) => d.defaultWarningMode == mode)
.toList(growable: false)
.map((d) => ' ${d.warningName}: ${d.shortHelp}')
class PackageWarningDefinition implements Comparable<PackageWarningDefinition> {
final String warningName;
final String shortHelp;
final List<String> longHelp;
final PackageWarning kind;
final PackageWarningMode defaultWarningMode;
const PackageWarningDefinition(
this.shortHelp, {
this.longHelp = const [],
this.defaultWarningMode = PackageWarningMode.warn,
int compareTo(PackageWarningDefinition other) {
return warningName.compareTo(other.warningName);
/// Same as [packageWarningDefinitions], except keyed by the warning name.
final Map<String, PackageWarningDefinition> packageWarningsByName = {
for (final definition in packageWarningDefinitions.values)
definition.warningName: definition
/// Provides description text and command line flags for warnings.
/// TODO(jcollins-g): Actually use this for command line flags.
const Map<PackageWarning, PackageWarningDefinition> packageWarningDefinitions =
PackageWarning.ambiguousDocReference: PackageWarningDefinition(
'A comment reference could refer to two or more different objects'),
PackageWarning.ambiguousReexport: PackageWarningDefinition(
'A symbol is exported from private to public in more than one library '
'and dartdoc can not determine which one is canonical',
longHelp: [
"Use {@canonicalFor $_namePlaceholder} in the desired library's",
"documentation to resolve the ambiguity and/or override dartdoc's",
'decision, or structure your package so the reexport is less',
'ambiguous. The symbol will still be referenced in all candidates --',
'this only controls the location where it will be written and which',
'library will be displayed in navigation for the relevant pages. The',
'flag --ambiguous-reexport-scorer-min-confidence allows you to set the',
'threshold at which this warning will appear.'
PackageWarning.ignoredCanonicalFor: PackageWarningDefinition(
'A @canonicalFor tag refers to a library which this symbol can not be '
'canonical for'),
PackageWarning.noCanonicalFound: PackageWarningDefinition(
'A symbol is part of the public interface for this package, but no '
'library documented with this package documents it so dartdoc can '
'not link to it'),
PackageWarning.noDefiningLibraryFound: PackageWarningDefinition(
'The defining library for an element could not be found; the library may '
'be imported or exported with a non-standard URI',
longHelp: [
'For non-canonicalized import or export paths, dartdoc can sometimes lose ',
'track of the defining library for an element. If this happens, canonicalization',
'will assume that reexported elements are defined somewhere it deems "reasonable", ',
'defaulting first to the enclosing context\'s definingLibrary if available, ',
'or the library is is visible in. This can lead to confusing documentation ',
'structure that implies duplicate code where none exists.',
'To correct this, canonicalize all paths in the import or export chain',
'making this symbol visible.',
"For example: 'change `import 'package:dartdoc/src/model/../model/extension_target.dart';`",
"to `import 'package:dartdoc/src/model/extension_target.dart';`",
"or `import 'src/../src/foo.dart';`",
"to `import 'src/foo.dart';",
"or `import 'package:dartdoc//lib//foo.dart';",
"to `import 'package:dartdoc/lib/foo.dart';",
defaultWarningMode: PackageWarningMode.error),
PackageWarning.notImplemented: PackageWarningDefinition(
'The code makes use of a feature that is not yet implemented in dartdoc'),
PackageWarning.noDocumentableLibrariesInPackage: PackageWarningDefinition(
'The package is to be documented but has no Dart libraries to document',
longHelp: [
'Dartdoc could not find any public libraries to document in',
'$_namePlaceholder, but documentation was requested. This might be',
'expected for an asset only package, in which case, disable this',
'warning in your dartdoc_options.yaml file.',
PackageWarning.noLibraryLevelDocs: PackageWarningDefinition(
'There are no library level docs for this library'),
PackageWarning.packageOrderGivesMissingPackageName: PackageWarningDefinition(
'The category-order flag on the command line was given the name of a nonexistent package'),
PackageWarning.reexportedPrivateApiAcrossPackages: PackageWarningDefinition(
'One or more libraries reexports private API members from outside its own package'),
PackageWarning.unresolvedDocReference: PackageWarningDefinition(
'A comment reference could not be found in parameters, enclosing class, enclosing library, or at the top level of any documented library with the package'),
PackageWarning.brokenLink: PackageWarningDefinition(PackageWarning.brokenLink,
'broken-link', 'Dartdoc generated a link to a non-existent file'),
PackageWarning.unknownDirective: PackageWarningDefinition(
'A comment contains an unknown directive'),
PackageWarning.unknownMacro: PackageWarningDefinition(
'A comment reference contains an unknown macro'),
PackageWarning.orphanedFile: PackageWarningDefinition(
'Dartdoc generated files that are unreachable from the index'),
PackageWarning.unknownFile: PackageWarningDefinition(
'A leftover file exists in the tree that dartdoc did not write in this pass'),
PackageWarning.missingFromSearchIndex: PackageWarningDefinition(
'A file generated by dartdoc is not present in the generated index.json'),
PackageWarning.typeAsHtml: PackageWarningDefinition(
'Use of <> in a comment for type parameters is being treated as HTML by markdown',
defaultWarningMode: PackageWarningMode.ignore),
PackageWarning.invalidParameter: PackageWarningDefinition(
'A parameter given to a dartdoc directive was invalid.',
defaultWarningMode: PackageWarningMode.error),
PackageWarning.toolError: PackageWarningDefinition(PackageWarning.toolError,
'tool-error', 'Unable to execute external tool.',
defaultWarningMode: PackageWarningMode.error),
PackageWarning.deprecated: PackageWarningDefinition(PackageWarning.deprecated,
'deprecated', 'A dartdoc directive has a deprecated format.'),
PackageWarning.unresolvedExport: PackageWarningDefinition(
'An export refers to a URI that cannot be resolved.',
defaultWarningMode: PackageWarningMode.error),
PackageWarning.duplicateFile: PackageWarningDefinition(
'Dartdoc is trying to write to a duplicate filename based on the names '
'of Dart symbols.',
longHelp: [
'Dartdoc generates a path and filename to write to for each symbol.',
'$_namePlaceholder conflicts with another symbol in the generated',
'path, and therefore can not be written out. Changing the name,',
'library name, or class name (if appropriate) of one of the',
'conflicting items can resolve the conflict. Alternatively, use the',
"@nodoc tag in one symbol's documentation comments to hide it."
defaultWarningMode: PackageWarningMode.error),
PackageWarning.missingConstantConstructor: PackageWarningDefinition(
'Dartdoc can not show the value of a constant because its constructor could not be resolved.',
longHelp: [
'To resolve a constant into its literal value, Dartdoc relies on the',
"analyzer to resolve the constructor. The analyzer didn't provide",
'the constructor for $_namePlaceholder, which is usually due to an',
'error in the code. Use the analyzer to find missing imports.',
// Defaults to ignore as this doesn't impact the docs severely but is
// useful for debugging package structure.
defaultWarningMode: PackageWarningMode.ignore),
PackageWarning.missingCodeBlockLanguage: PackageWarningDefinition(
'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',
'specify ```dart or ~~~dart.'
defaultWarningMode: PackageWarningMode.ignore),
/// Something that package warnings can be called on. Optionally associated
/// with an analyzer [element].
mixin Warnable implements Canonicalization, CommentReferable {
Element? get element;
void warn(
PackageWarning kind, {
String? message,
Iterable<Locatable> referredFrom = const [],
Iterable<String> extendedDebug = const [],
}) {
packageGraph.warnOnElement(this, kind,
message: message,
referredFrom: referredFrom,
extendedDebug: extendedDebug);
// The kinds of warnings that can be displayed when documenting a package.
enum PackageWarning {
ambiguousDocReference('ambiguous doc reference {0}'),
// Fix these warnings by adding the original library exporting the symbol with
// `--include`, by using `--auto-include-dependencies`, or by using
// `--exclude` to hide one of the libraries involved.
'ambiguous reexport of {0}, canonicalization candidates: {1}'),
"library says it is {@canonicalFor {0}} but {0} can't be canonical "
// Fix these warnings by adding libraries with `--include`, or by using
// `--auto-include-dependencies`.
// TODO(jcollins-g): pipeline references through `linkedName` for error
// messages and warn for non-public canonicalization errors.
noCanonicalFound('no canonical library found for {0}, not linking'),
noDefiningLibraryFound('could not find the defining library for {0}; the '
'library may be imported or exported with a non-standard URI'),
noDocumentableLibrariesInPackage('{0} has no documentable libraries'),
noLibraryLevelDocs('{0} has no library level documentation comments'),
"--package-order gives invalid package name: '{0}'"),
'private API of {0} is reexported by libraries in other packages: '),
unresolvedDocReference('unresolved doc reference [{0}]',
referredFromPrefix: 'in documentation inherited from'),
unknownDirective('undefined directive: {0}'),
unknownMacro('undefined macro [{0}]'),
unknownHtmlFragment('undefined HTML fragment identifier [{0}]'),
brokenLink('dartdoc generated a broken link to: {0}',
warnablePrefix: 'to element', referredFromPrefix: 'linked to from'),
duplicateFile('failed to write file at: {0}',
warnablePrefix: 'for symbol',
referredFromPrefix: 'conflicting with file already generated by'),
orphanedFile('dartdoc generated a file orphan: {0}'),
unknownFile('dartdoc detected an unknown file in the doc tree: {0}'),
'dartdoc generated a file not in the search index: {0}'),
// The message for this warning can contain many punctuation and other
// symbols, so bracket with a triple quote for defense.
typeAsHtml('generic type handled as HTML: """{0}"""'),
invalidParameter('invalid parameter to dartdoc directive: {0}'),
toolError('tool execution failed: {0}'),
deprecated('deprecated dartdoc usage: {0}'),
unresolvedExport('unresolved export uri: {0}'),
missingConstantConstructor('constant constructor missing: {0}'),
missingExampleFile('example file not found: {0}'),
missingCodeBlockLanguage('missing code block language: {0}');
final String template;
final String warnablePrefix;
final String referredFromPrefix;
const PackageWarning(
this.template, {
this.warnablePrefix = 'from',
this.referredFromPrefix = 'referred to by',
String messageFor(List<String> messageParts) {
var message = template;
for (var i = 0; i < messageParts.length; i++) {
message = message.replaceAll('{$i}', messageParts[i]);
return message;
String messageForWarnable(Warnable warnable) =>
'$warnablePrefix ${warnable.safeWarnableName}: ${warnable.location}';
String messageForReferral(Locatable referral) =>
'$referredFromPrefix ${referral.safeWarnableName}: ${referral.location}';
/// Used to declare defaults for a particular package warning.
enum PackageWarningMode {
/// Warnings it is OK to skip if we can determine the warnable isn't documented.
/// In particular, this set should not include warnings around public/private
/// or canonicalization problems, because those can break the isDocumented()
/// check.
const Set<PackageWarning> skipWarningIfNotDocumentedFor = {
class PackageWarningOptions {
final Map<PackageWarning, PackageWarningMode> warningModes = {};
PackageWarningOptions() {
for (var definition in packageWarningDefinitions.values) {
switch (definition.defaultWarningMode) {
case PackageWarningMode.warn:
case PackageWarningMode.error:
case PackageWarningMode.ignore:
static PackageWarningOptions fromOptions(
DartdocSyntheticOption<PackageWarningOptions> option,
Folder dir,
PackageMetaProvider packageMetaProvider,
) {
// First, initialize defaults.
var newOptions = PackageWarningOptions();
var packageMeta = packageMetaProvider.fromDir(dir)!;
// Interpret errors/warnings/ignore options. In the event of conflict,
// warning overrides error and ignore overrides warning.
var errorsForDir =
option.parent.getValueAs<List<String>?>('errors', dir) ?? [];
for (var warningName in errorsForDir) {
var packageWarnings = packageWarningsByName[warningName];
if (packageWarnings != null) {
var warningsForDir =
option.parent.getValueAs<List<String>?>('warnings', dir) ?? [];
for (var warningName in warningsForDir) {
var packageWarnings = packageWarningsByName[warningName];
if (packageWarnings != null) {
var ignoredForDir =
option.parent.getValueAs<List<String>?>('ignore', dir) ?? [];
for (var warningName in ignoredForDir) {
var packageWarnings = packageWarningsByName[warningName];
if (packageWarnings != null) {
// Check whether warnings are allowed at all in this package.
var allowWarningsInPackages =
option.parent.getValueAs<List<String>?>('allowWarningsInPackages', dir);
var allowErrorsInPackages =
option.parent.getValueAs<List<String>?>('allowErrorsInPackages', dir);
var ignoreWarningsInPackages = option.parent
.getValueAs<List<String>?>('ignoreWarningsInPackages', dir);
var ignoreErrorsInPackages =
option.parent.getValueAs<List<String>?>('ignoreErrorsInPackages', dir);
void ignoreWarning(PackageWarning kind) {
if (allowWarningsInPackages != null &&
!allowWarningsInPackages.contains( {
if (allowErrorsInPackages != null &&
!allowErrorsInPackages.contains( {
if (ignoreWarningsInPackages != null &&
ignoreWarningsInPackages.contains( {
if (ignoreErrorsInPackages != null &&
ignoreErrorsInPackages.contains( {
return newOptions;
void ignore(PackageWarning kind) =>
warningModes[kind] = PackageWarningMode.ignore;
void warn(PackageWarning kind) =>
warningModes[kind] = PackageWarningMode.warn;
void error(PackageWarning kind) =>
warningModes[kind] = PackageWarningMode.error;
PackageWarningMode? getMode(PackageWarning kind) => warningModes[kind];
class PackageWarningCounter {
final Map<Element?, Map<PackageWarning, Set<String>>> _countedWarnings = {};
final _items = <Jsonable>[];
final _displayedWarningCounts = <PackageWarning, int>{};
final PackageGraph packageGraph;
int _errorCount = 0;
/// The total amount of errors this package has experienced.
int get errorCount => _errorCount;
int _warningCount = 0;
/// The total amount of warnings this package has experienced.
int get warningCount => _warningCount;
/// An unmodifiable map view of all counted warnings related by their element,
/// warning type, and message.
UnmodifiableMapView<Element?, Map<PackageWarning, Set<String>>>
get countedWarnings => UnmodifiableMapView(_countedWarnings);
/// Actually write out the warning.
/// Assumes it is already counted with [addWarning].
void _writeWarning(PackageWarning kind, PackageWarningMode? mode,
bool verboseWarnings, String name, String fullMessage) {
if (mode == PackageWarningMode.ignore) {
String? type;
if (mode == PackageWarningMode.error) {
type = 'error';
} else if (mode == PackageWarningMode.warn) {
type = 'warning';
if (type != null) {
var entry = ' $type: $fullMessage';
var displayedWarningCount = _displayedWarningCounts.increment(kind);
var packageWarningDefinition = packageWarningDefinitions[kind]!;
if (displayedWarningCount == 1 &&
verboseWarnings &&
packageWarningDefinition.longHelp.isNotEmpty) {
// First time we've seen this warning. Give a little extra info.
final separator = '\n ';
var verboseOut =
.replaceAll(_namePlaceholder, name);
entry = '$entry$verboseOut';
assert(entry == entry.trimRight());
_items.add(_JsonWarning(type, kind, fullMessage, entry));
for (var item in _items) {
/// If this package has had any warnings counted.
bool get hasWarnings => _countedWarnings.isNotEmpty;
/// Returns `true` if we've already warned for this
/// combination of [element], [kind], and [message].
bool hasWarning(Warnable? element, PackageWarning kind, String message) {
if (element == null) {
return false;
final warning = _countedWarnings[element.element];
if (warning != null) {
final messages = warning[kind];
return messages != null && messages.contains(message);
return false;
/// Adds the warning to the counter, and writes out the fullMessage string
/// if configured to do so.
void addWarning(Warnable? element, PackageWarning kind, String message,
String fullMessage) {
assert(!hasWarning(element, kind, message));
// TODO(jcollins-g): Make addWarning not accept nulls for element.
PackageWarningOptionContext config =
element?.config ?? packageGraph.defaultPackage.config;
PackageWarningMode? warningMode;
var isLocal = element?.package.isLocal ?? true;
if (!config.allowNonLocalWarnings && !isLocal) {
warningMode = PackageWarningMode.ignore;
} else {
warningMode = config.packageWarningOptions.getMode(kind);
if (warningMode == PackageWarningMode.warn) {
_warningCount += 1;
} else if (warningMode == PackageWarningMode.error) {
_errorCount += 1;
if (element != null) {
.putIfAbsent(element.element, () => {})
.putIfAbsent(kind, () => {})
_writeWarning(kind, warningMode, config.verboseWarnings,
element.fullyQualifiedName, fullMessage);
String toString() {
final errors = '$errorCount ${errorCount == 1 ? "error" : "errors"}';
final warnings =
'$warningCount ${warningCount == 1 ? "warning" : "warnings"}';
return '$errors, $warnings';
class _JsonWarning extends Jsonable {
final String type;
final PackageWarning kind;
final String message;
final String text;
_JsonWarning(this.type, this.kind, this.message, this.text);
Map<String, dynamic> toJson() => {
'type': type,
'kind': packageWarningDefinitions[kind]!.warningName,
'message': message,
'text': text
extension on Map<PackageWarning, int> {
int increment(PackageWarning kind) {
if (this[kind] == null) {
this[kind] = 1;
return 1;
} else {
this[kind] = this[kind]! + 1;
return this[kind]!;