blob: a1a686b5fc3c4860842a892d5c393c602b581c54 [file] [edit]
// Copyright (c) 2026, 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:dartdoc/src/warnings.dart';
import 'package:test/test.dart';
import 'package:test_reflective_loader/test_reflective_loader.dart';
import 'dartdoc_test_base.dart';
import 'src/test_descriptor_utils.dart' as d;
import 'src/utils.dart';
void main() {
defineReflectiveSuite(() {
defineReflectiveTests(DocReferenceTargetDiffersTest);
});
}
/// Tests for [PackageWarning.docReferenceTargetDiffers], which is reported
/// when dartdoc and the analyzer resolve a doc comment reference to different
/// elements.
@reflectiveTest
class DocReferenceTargetDiffersTest extends DartdocTestBase {
@override
String get libraryName => 'target';
bool _hasDiffersWarning(Warnable warnable, String reference) =>
warnable.packageGraph.packageWarningCounter.hasWarning(
warnable, PackageWarning.docReferenceTargetDiffers, reference);
void test_isIgnoredByDefault() async {
var library = await bootPackageWithLibrary('int x = 0;');
expect(
library.config.packageWarningOptions
.getMode(PackageWarning.docReferenceTargetDiffers),
PackageWarningMode.ignore,
);
}
void test_inheritedDocumentation_staticShadowing_warns() async {
var library = await bootPackageWithLibrary('''
class A {
static void parse() {}
/// Processes data by invoking [parse].
void process() {}
}
class B extends A {
// Unrelated to A.parse; it only happens to share the name.
static void parse() {}
@override
void process() {}
}
''');
var bProcess = library.classes.named('B').instanceMethods.named('process');
// Dartdoc re-resolves the inherited comment in `B`, linking `B.parse`; the
// analyzer resolved `[parse]` where the comment was written, to `A.parse`.
expect(bProcess.documentationAsHtml, contains('B/parse.html'));
expect(_hasDiffersWarning(bProcess, '[parse] links to target.B.parse'),
isTrue);
expect(_hasDiffersWarning(bProcess, 'A.parse'), isTrue);
// At the definition site both agree.
var aProcess = library.classes.named('A').instanceMethods.named('process');
expect(_hasDiffersWarning(aProcess, 'parse'), isFalse);
}
void test_inheritedDocumentation_overriddenMember_warns() async {
var library = await bootPackageWithLibrary('''
class A {
/// See [other].
void m() {}
void other() {}
}
class B extends A {
@override
void m() {}
@override
void other() {}
}
''');
var bM = library.classes.named('B').instanceMethods.named('m');
expect(bM.documentationAsHtml, contains('B/other.html'));
expect(_hasDiffersWarning(bM, '[other] links to target.B.other'), isTrue);
}
void test_inheritedDocumentation_inheritedMember_doesNotWarn() async {
var library = await bootPackageWithLibrary('''
class A {
/// See [other].
void m() {}
void other() {}
}
class B extends A {
@override
void m() {}
}
''');
var bM = library.classes.named('B').instanceMethods.named('m');
// `B.other` is inherited, not overridden, so it is the same element as
// `A.other`.
expect(bM.documentationAsHtml, contains('other.html'));
expect(_hasDiffersWarning(bM, 'other'), isFalse);
}
void test_sameTarget_doesNotWarn() async {
var library = await bootPackageWithLibrary('''
class Other {}
/// Text [Other].
int x = 0;
''');
var x = library.properties.named('x');
expect(x.documentationAsHtml, contains('<a href='));
expect(_hasDiffersWarning(x, 'Other'), isFalse);
}
void test_fieldAndGetter_doesNotWarn() async {
var library = await bootPackageWithLibrary('''
class C {
int field = 0;
int get getter => 0;
/// Text [field] and [getter].
void m() {}
}
''');
var m = library.classes.named('C').instanceMethods.named('m');
// The analyzer resolves `[field]` to the implicit getter; dartdoc links
// the field. Both are normalized to the same element.
expect(m.documentationAsHtml, contains('field.html'));
expect(m.documentationAsHtml, contains('getter.html'));
expect(_hasDiffersWarning(m, 'field'), isFalse);
expect(_hasDiffersWarning(m, 'getter'), isFalse);
}
void test_inheritedDocumentation_inheritedGetter_doesNotWarn() async {
var library = await bootPackageWithLibrary('''
class A {
int get getter => 0;
/// Text [getter].
void m() {}
}
class B extends A {
@override
void m() {}
}
''');
var bM = library.classes.named('B').instanceMethods.named('m');
// Rendered in `B`, the inherited comment is re-resolved through the
// children of `B`, linking the synthetic field of the inherited getter;
// the analyzer resolved `[getter]` to the getter itself.
expect(bM.documentationAsHtml, contains('getter.html'));
expect(_hasDiffersWarning(bM, 'getter'), isFalse);
}
void test_memberOfGenericSupertype_doesNotWarn() async {
var library = await bootPackageWithLibrary('''
class Base<T> {
T get value => throw '';
void run() {}
}
/// Text [value] and [run].
class Sub extends Base<int> {}
''');
var sub = library.classes.named('Sub');
// The analyzer resolves members inherited from `Base<int>` to substituted
// copies of the declarations in `Base<T>`; dartdoc links the declarations.
expect(sub.documentationAsHtml, contains('value.html'));
expect(sub.documentationAsHtml, contains('run.html'));
expect(_hasDiffersWarning(sub, 'value'), isFalse);
expect(_hasDiffersWarning(sub, 'run'), isFalse);
}
void test_docImportPrefix_doesNotWarn() async {
var library = await bootPackageWithLibrary(
'''
/// Text [async] and [async.Future].
int x = 0;
''',
libraryPreamble: "/// @docImport 'dart:async' as async;",
additionalArguments: ['--link-to-remote'],
);
var x = library.properties.named('x');
// The analyzer resolves `[async]` to the prefix, dartdoc links the
// library; both are normalized to the library.
expect(x.documentationAsHtml, contains('<a href='));
expect(_hasDiffersWarning(x, 'async'), isFalse);
}
void test_unscoped_doesNotWarn() async {
var library = await bootPackageWithLibrary(
'''
/// Text [Other].
int x = 0;
''',
extraFiles: [d.file('lib/other.dart', 'class Other {}')],
);
var x = library.properties.named('x');
// The analyzer did not resolve the reference at all; that is the
// `unscoped-doc-reference` case, not this one.
expect(x.documentationAsHtml, contains('<a href='));
expect(_hasDiffersWarning(x, 'Other'), isFalse);
expect(
x.packageGraph.packageWarningCounter
.hasWarning(x, PackageWarning.unscopedDocReference, 'Other'),
isTrue,
);
}
}