blob: 29d749eea9ef9fae141c66349c608af2513e04c5 [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:io';
import 'dart:math' as math;
import 'package:analyzer/dart/element/element.dart';
import 'package:analyzer/file_system/file_system.dart';
import 'package:collection/collection.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';
import 'package:dartdoc/src/utils.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,
help: 'Additional warning names to force as errors. Specify an empty '
'list to force defaults (overriding dartdoc_options.yaml)\n'
DartdocOptionArgFile<List<String>?>('ignore', null, resourceProvider,
splitCommas: true,
help: 'Additional warning names to ignore. Specify an empty list to '
'force defaults (overriding dartdoc_options.yaml).\n'
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).\n'
// Synthetic option uses a factory to build a PackageWarningOptions from all
// the above flags.
(DartdocSyntheticOption<PackageWarningOptions> option, Folder dir) =>
PackageWarningOptions.fromOptions(option, dir, packageMetaProvider),
/// Something that package warnings can be reported on. Optionally associated
/// with an analyzer [element].
mixin Warnable implements CommentReferable, Documentable, Locatable {
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 implements Comparable<PackageWarning> {
'ambiguous doc reference {0}',
'A comment reference could refer to two or more different objects',
// 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}',
'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.',
"library says it is {@canonicalFor {0}} but {0} can't be canonical "
'A @canonicalFor tag refers to a library which this symbol can not be '
'canonical for',
// 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.
'no canonical library found for {0}, not linking',
'A symbol is part of the public interface for this package, but no '
'library documented with this package documents it so dartdoc cannot '
'link to it',
'{0} has no documentable libraries',
'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.',
'{0} has no library level documentation comments',
shortHelp: 'There are no library level docs for this library',
"--package-order gives invalid package name: '{0}'",
'The category-order flag on the command line was given the name of a '
'nonexistent package',
'private API of {0} is reexported by libraries in other packages: ',
'One or more libraries reexports private API members from outside its '
'own package',
'unresolved doc reference [{0}]',
'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',
referredFromPrefix: 'in documentation inherited from',
'undefined macro [{0}]',
shortHelp: 'A comment reference contains an unknown macro',
'undefined HTML fragment identifier [{0}]',
'Dartdoc attempted to inject an unknown block of HTML, indicating a '
'bug in Dartdoc',
'dartdoc generated a broken link to: {0}',
shortHelp: 'Dartdoc generated a link to a non-existent file',
warnablePrefix: 'to element',
referredFromPrefix: 'linked to from',
'failed to write file at: {0}',
'Dartdoc is trying to write to a duplicate filename based on the names '
'of Dart symbols.',
'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` directive in one symbol's documentation comment to hide it.",
warnablePrefix: 'for symbol',
referredFromPrefix: 'conflicting with file already generated by',
defaultWarningMode: PackageWarningMode.error,
'dartdoc generated a file orphan: {0}',
shortHelp: 'Dartdoc generated files that are unreachable from the index',
'dartdoc detected an unknown file in the doc tree: {0}',
'A leftover file exists in the tree that dartdoc did not write in this '
'dartdoc generated a file not in the search index: {0}',
shortHelp: 'A file generated by dartdoc is not present in the generated '
'index.json file',
// The message for this warning can contain many punctuation and other
// symbols, so bracket with a triple quote for defense.
'generic type handled as HTML: """{0}"""',
'Use of <> in a comment for type parameters is being treated as HTML '
'by Markdown',
defaultWarningMode: PackageWarningMode.ignore,
'invalid parameter to dartdoc directive: {0}',
shortHelp: 'A parameter given to a dartdoc directive was invalid.',
defaultWarningMode: PackageWarningMode.error,
'tool execution failed: {0}',
shortHelp: 'Unable to execute external tool.',
defaultWarningMode: PackageWarningMode.error,
'deprecated dartdoc usage: {0}',
shortHelp: 'A dartdoc directive has a deprecated format.',
'unresolved export uri: {0}',
shortHelp: 'An export refers to a URI that cannot be resolved.',
defaultWarningMode: PackageWarningMode.error,
'constant constructor missing: {0}',
'Dartdoc can not show the value of a constant because its constructor '
'could not be resolved.',
'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 resolve the issue.',
// Defaults to ignore as this doesn't impact the docs severely but is
// useful for debugging package structure.
defaultWarningMode: PackageWarningMode.ignore,
'example file not found: {0}',
"A file which is indicated by an '{@example}' directive could not be "
'missing code block language: {0}',
shortHelp: 'A fenced code block is missing a specified language.',
'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,
/// The name which can be used at the command line to enable this warning.
final String _flagName;
/// The message template, with substitutions.
final String _template;
final String _warnablePrefix;
final String _referredFromPrefix;
final String _shortHelp;
final String _longHelp;
final PackageWarningMode _defaultWarningMode;
const PackageWarning(
this._template, {
required String shortHelp,
String longHelp = '',
String warnablePrefix = 'from',
String referredFromPrefix = 'referred to by',
PackageWarningMode defaultWarningMode = PackageWarningMode.warn,
}) : _shortHelp = shortHelp,
_longHelp = longHelp,
_warnablePrefix = warnablePrefix,
_referredFromPrefix = referredFromPrefix,
_defaultWarningMode = defaultWarningMode;
static PackageWarning? _byName(String name) =>
PackageWarning.values.firstWhereOrNull((w) => w._flagName == name);
int compareTo(PackageWarning other) {
return _flagName.compareTo(other._flagName);
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 {
String get _warningsListHelpText {
return (PackageWarning.values
.where((w) => w._defaultWarningMode == this)
.toList(growable: false)
.map((w) => ' ${w._flagName}: ${w._shortHelp}')
/// Warnings which are 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 PackageWarning.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 packageWarning = PackageWarning._byName(warningName);
if (packageWarning != null) {
var warningsForDir =
option.parent.getValueAs<List<String>?>('warnings', dir) ?? [];
for (var warningName in warningsForDir) {
var packageWarning = PackageWarning._byName(warningName);
if (packageWarning != null) {
var ignoredForDir =
option.parent.getValueAs<List<String>?>('ignore', dir) ?? [];
for (var warningName in ignoredForDir) {
var packageWarning = PackageWarning._byName(warningName);
if (packageWarning != 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);
/// Logs [packageWarning].
/// Assumes it is already counted with [addWarning].
void _writeWarning(PackageWarning packageWarning, PackageWarningMode? mode,
bool verboseWarnings, String name, String fullMessage) {
if (mode == PackageWarningMode.ignore) {
var type = switch (mode) {
PackageWarningMode.error => 'error',
PackageWarningMode.warn => 'warning',
_ => null,
if (type != null) {
var entry = ' $type: $fullMessage';
var displayedWarningCount =
if (displayedWarningCount == 1 &&
verboseWarnings &&
packageWarning._longHelp.isNotEmpty) {
// First time we've seen this warning. Give a little extra info.
var longHelpLines = packageWarning._longHelp
.map((line) => line.replaceAll(_namePlaceholder, name))
.map((line) =>
_wrapText(line, prefix: ' ', width: _messageWidth));
var verboseOut = longHelpLines.join('\n');
entry = '$entry\n$verboseOut';
assert(entry == entry.trimRight());
_items.add(_JsonWarning(type, packageWarning, fullMessage, entry));
for (var item in _items) {
/// If this package has had any warnings counted.
bool get hasWarnings => _countedWarnings.isNotEmpty;
/// Whether 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;
var isLocal = element?.package.isLocal ?? true;
var warningMode = !isLocal && !config.allowNonLocalWarnings
? PackageWarningMode.ignore
: config.packageWarningOptions.getMode(kind);
if (warningMode == PackageWarningMode.warn) {
_warningCount += 1;
} else if (warningMode == PackageWarningMode.error) {
_errorCount += 1;
var elementName = element == null ? '<global>' : element.fullyQualifiedName;
.putIfAbsent(element?.element, () => {})
.putIfAbsent(kind, () => {})
String toString() {
final errors = '$errorCount ${pluralize('error', errorCount)}';
final warnings = '$warningCount ${pluralize('warning', warningCount)}';
return '$errors, $warnings';
/// Wraps [text] to the given [width], if provided.
/// This function is taken from the 'dartdev' package, which has tests.
String _wrapText(String text, {required int width, String prefix = ''}) {
// For convenience, the caller specifies the line width, but effectively, we
// subtract out the width of the prefix.
width = width - prefix.length;
var buffer = StringBuffer(prefix);
var lineMaxEndIndex = width;
var lineStartIndex = 0;
while (true) {
if (lineMaxEndIndex >= text.length) {
buffer.write(text.substring(lineStartIndex, text.length));
} else {
var lastSpaceIndex = text.lastIndexOf(' ', lineMaxEndIndex);
if (lastSpaceIndex == -1 || lastSpaceIndex <= lineStartIndex) {
// No space between [lineStartIndex] and [lineMaxEndIndex]. Get the
// _next_ space.
lastSpaceIndex = text.indexOf(' ', lineMaxEndIndex);
if (lastSpaceIndex == -1) {
// No space at all after [lineStartIndex].
lastSpaceIndex = text.length;
buffer.write(text.substring(lineStartIndex, lastSpaceIndex));
buffer.write(text.substring(lineStartIndex, lastSpaceIndex));
lineStartIndex = lastSpaceIndex + 1;
lineMaxEndIndex = lineStartIndex + width;
return buffer.toString();
/// The width that messages in the terminal should be limited to.
/// If `stdout` has a terminal, use that terminal's width capped to 120
/// characters wide. Otherwise, use a width of 80.
final _messageWidth =
stdout.hasTerminal ? math.min(stdout.terminalColumns, 120) : 80;
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': kind._flagName,
'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]!;