diff --git a/lib/src/model/accessor.dart b/lib/src/model/accessor.dart index 8f0c4e3f15..ad649a2e98 100644 --- a/lib/src/model/accessor.dart +++ b/lib/src/model/accessor.dart @@ -104,7 +104,7 @@ class Accessor extends ModelElement { void warn( PackageWarning kind, { String? message, - Iterable referredFrom = const [], + Iterable referredFrom = const [], Iterable extendedDebug = const [], }) { enclosingCombo.warn(kind, diff --git a/lib/src/model/category.dart b/lib/src/model/category.dart index 97b0792840..70834f0f17 100644 --- a/lib/src/model/category.dart +++ b/lib/src/model/category.dart @@ -92,7 +92,7 @@ final class Category extends LibraryContainer PackageGraph get packageGraph => package.packageGraph; @override - List get documentationFrom => [this]; + List get documentationFrom => [this]; @override DocumentLocation get documentedWhere => package.documentedWhere; diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 00941cd160..48335beafd 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -11,7 +11,6 @@ import 'package:crypto/crypto.dart' as crypto; import 'package:dartdoc/src/model/documentable.dart'; import 'package:dartdoc/src/model/documentation.dart'; import 'package:dartdoc/src/model/inheritable.dart'; -import 'package:dartdoc/src/model/locatable.dart'; import 'package:dartdoc/src/model/model_element.dart'; import 'package:dartdoc/src/model/source_code_mixin.dart'; import 'package:dartdoc/src/utils.dart'; @@ -38,8 +37,7 @@ final _htmlInjectRegExp = RegExp(r'([a-f0-9]+)'); /// /// [_processCommentWithoutTools] and [processComment] are the primary /// entrypoints. -mixin DocumentationComment - implements Documentable, Warnable, HasLocation, SourceCode { +mixin DocumentationComment implements Documentable, Warnable, SourceCode { @override Element get element; diff --git a/lib/src/model/locatable.dart b/lib/src/model/locatable.dart deleted file mode 100644 index fddda1db5e..0000000000 --- a/lib/src/model/locatable.dart +++ /dev/null @@ -1,38 +0,0 @@ -// Copyright (c) 2019, 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/model/model.dart'; - -/// Something that can be located for warning purposes. -abstract interface class HasLocation { - /// The [Locatable](s) from which we will get documentation. - /// - /// Can be more than one if this is a [Field] composing documentation from - /// multiple [Accessor]s. - /// - /// This will walk up the inheritance hierarchy to find docs, if the current - /// class doesn't have docs for this element. - List get documentationFrom; - - String get fullyQualifiedName; - - String? get href; - - /// A string indicating the URI of this Locatable. - String get location; - - /// Whether this is the "canonical" copy of an element. - /// - /// Generally, a canonical element must be public, along with possible other - /// requirements. - /// - /// In order for an element to be documented, it must be canonical, and have - /// documentation. - bool get isCanonical; -} - -extension NullableHasLocation on HasLocation? { - String get safeWarnableName => - this?.fullyQualifiedName.replaceFirst(':', '-') ?? ''; -} diff --git a/lib/src/model/model.dart b/lib/src/model/model.dart index fc682ed358..568e6e410d 100644 --- a/lib/src/model/model.dart +++ b/lib/src/model/model.dart @@ -25,7 +25,6 @@ export 'inheritable.dart'; export 'inheriting_container.dart'; export 'library.dart'; export 'library_container.dart'; -export 'locatable.dart'; export 'method.dart'; export 'mixin.dart'; export 'model_element.dart'; diff --git a/lib/src/model/model_element.dart b/lib/src/model/model_element.dart index 571ab587df..ef1c26c685 100644 --- a/lib/src/model/model_element.dart +++ b/lib/src/model/model_element.dart @@ -58,7 +58,7 @@ import 'package:path/path.dart' as p show Context; /// public interface perspective. abstract class ModelElement with CommentReferable, Warnable, Nameable, SourceCode, DocumentationComment - implements Comparable, Documentable, HasLocation { + implements Comparable, Documentable { // TODO(jcollins-g): This really wants a "member that has a type" class. final Element? _originalMember; final Library _library; diff --git a/lib/src/model/package.dart b/lib/src/model/package.dart index ad7c279ae2..94389e9e1d 100644 --- a/lib/src/model/package.dart +++ b/lib/src/model/package.dart @@ -104,7 +104,7 @@ final class Package extends LibraryContainer String? get belowSidebarPath => null; @override - List get documentationFrom => [this]; + List get documentationFrom => [this]; /// Return true if the code has defined non-default categories for libraries /// in this package. diff --git a/lib/src/model/package_graph.dart b/lib/src/model/package_graph.dart index ac590ed21a..c0822a5dc8 100644 --- a/lib/src/model/package_graph.dart +++ b/lib/src/model/package_graph.dart @@ -388,7 +388,7 @@ class PackageGraph with CommentReferable, Nameable { void warnOnElement(Warnable? warnable, PackageWarning kind, {String? message, - Iterable referredFrom = const [], + Iterable referredFrom = const [], Iterable extendedDebug = const []}) { var newEntry = (warnable?.element, kind, message); if (_warnAlreadySeen.contains(newEntry)) { @@ -406,7 +406,7 @@ class PackageGraph with CommentReferable, Nameable { void _warnOnElement(Warnable? warnable, PackageWarning kind, {required String message, - Iterable referredFrom = const [], + Iterable referredFrom = const [], Iterable extendedDebug = const []}) { if (warnable is ModelElement && kind == PackageWarning.ambiguousReexport) { // This sort of warning is only applicable to top level elements. diff --git a/lib/src/validator.dart b/lib/src/validator.dart index a5469b8d65..5e18f42a2b 100644 --- a/lib/src/validator.dart +++ b/lib/src/validator.dart @@ -9,7 +9,6 @@ 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/locatable.dart'; import 'package:dartdoc/src/model/model_element.dart'; import 'package:dartdoc/src/model/package_graph.dart'; import 'package:dartdoc/src/runtime_stats.dart'; @@ -236,7 +235,7 @@ class Validator { String origin, { String? referredFrom, }) { - final referredFromElements = {}; + final referredFromElements = {}; // Make all paths relative to origin. if (path.isWithin(origin, warnOn)) { diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index bcf9fdb354..10c9a8c464 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -14,6 +14,7 @@ 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'; +import 'package:meta/meta.dart'; const _namePlaceholder = '@@name@@'; @@ -94,13 +95,13 @@ List> createPackageWarningOptions( /// Something that package warnings can be reported on. Optionally associated /// with an analyzer [element]. -mixin Warnable implements CommentReferable, Documentable, HasLocation { +mixin Warnable implements CommentReferable, Documentable { Element? get element; void warn( PackageWarning kind, { String? message, - Iterable referredFrom = const [], + Iterable referredFrom = const [], Iterable extendedDebug = const [], }) { packageGraph.warnOnElement(this, kind, @@ -112,6 +113,28 @@ mixin Warnable implements CommentReferable, Documentable, HasLocation { /// Whether [documentationFrom] contains only one item, `this`. bool get documentationIsLocal => documentationFrom.length == 1 && identical(documentationFrom.first, this); + + /// The [Warnable]s from which we will get documentation. + /// + /// Can be more than one if this is a [Field] composing documentation from + /// multiple [Accessor]s. + /// + /// This will walk up the inheritance hierarchy to find docs, if the current + /// class doesn't have docs for this element. + List get documentationFrom; + + /// The URI of this [Warnable]. + @visibleForOverriding + String get location; + + /// Whether this is the "canonical" copy of an element. + /// + /// Generally, a canonical element must be public, along with possibly other + /// requirements. + /// + /// In order for an element to be documented, it must be canonical, and have + /// documentation. + bool get isCanonical; } /// The kinds of warnings that can be displayed when documenting a package. @@ -330,7 +353,7 @@ enum PackageWarning implements Comparable { String messageForWarnable(Warnable warnable) => '$_warnablePrefix ${warnable.safeWarnableName}: ${warnable.location}'; - String messageForReferral(HasLocation referral) => + String messageForReferral(Warnable referral) => '$_referredFromPrefix ${referral.safeWarnableName}: ${referral.location}'; } @@ -659,3 +682,8 @@ extension on Map { } } } + +extension NullableWarnableExtension on Warnable? { + String get safeWarnableName => + this?.fullyQualifiedName.replaceFirst(':', '-') ?? ''; +}