Refactor Locatable into an interface, HasLocation

Author: srawlins

lib/src/model/accessor.dart

@@ -16,7 +16,6 @@ import 'package:dartdoc/src/warnings.dart';
 
 /// Getters and setters.
 class Accessor extends ModelElement {
-
   @override
   final PropertyAccessorElement element;
 
@@ -105,7 +104,7 @@ class Accessor extends ModelElement {
   void warn(
     PackageWarning kind, {
     String? message,
-    Iterable<Locatable> referredFrom = const [],
+    Iterable<HasLocation> referredFrom = const [],
     Iterable<String> extendedDebug = const [],
   }) {
     enclosingCombo.warn(kind,

lib/src/model/canonicalization.dart

@@ -203,7 +203,7 @@ final class _Canonicalization {
   }
 }
 
-/// A pattern that can split [Locatable.location] strings.
+/// A pattern that can split [HasLocation.location] strings.
 final _locationSplitter = RegExp(r'(package:|[\\/;.])');
 
 /// This class represents the score for a particular element; how likely

lib/src/model/category.dart

@@ -16,7 +16,6 @@ class Category
         Nameable,
         Warnable,
         CommentReferable,
-        Locatable,
         MarkdownFileDocumentation,
         LibraryContainer,
         TopLevelContainer
@@ -96,7 +95,7 @@ class Category
   PackageGraph get packageGraph => package.packageGraph;
 
   @override
-  List<Locatable> get documentationFrom => [this];
+  List<HasLocation> get documentationFrom => [this];
 
   @override
   DocumentLocation get documentedWhere => package.documentedWhere;

lib/src/model/documentation_comment.dart

@@ -39,7 +39,7 @@ final _htmlInjectRegExp = RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
 /// [_processCommentWithoutTools] and [processComment] are the primary
 /// entrypoints.
 mixin DocumentationComment
-    implements Documentable, Warnable, Locatable, SourceCode {
+    implements Documentable, Warnable, HasLocation, SourceCode {
   @override
   Element get element;
 

lib/src/model/locatable.dart

@@ -5,19 +5,15 @@
 import 'package:dartdoc/src/model/model.dart';
 
 /// Something that can be located for warning purposes.
-mixin Locatable {
+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<Locatable> get documentationFrom;
-
-  /// Whether [documentationFrom] contains only one item, `this`.
-  bool get documentationIsLocal =>
-      documentationFrom.length == 1 && identical(documentationFrom.first, this);
+  List<HasLocation> get documentationFrom;
 
   String get fullyQualifiedName;
 
@@ -36,7 +32,7 @@ mixin Locatable {
   bool get isCanonical;
 }
 
-extension NullableLocatable on Locatable? {
+extension NullableHasLocation on HasLocation? {
   String get safeWarnableName =>
       this?.fullyQualifiedName.replaceFirst(':', '-') ?? '<unknown>';
 }

lib/src/model/model_element.dart

@@ -57,14 +57,8 @@ import 'package:path/path.dart' as p show Context;
 /// ModelElement will reference itself as part of the "wrong" [Library] from the
 /// public interface perspective.
 abstract class ModelElement
-    with
-        CommentReferable,
-        Warnable,
-        Locatable,
-        Nameable,
-        SourceCode,
-        DocumentationComment
-    implements Comparable<ModelElement>, Documentable {
+    with CommentReferable, Warnable, Nameable, SourceCode, DocumentationComment
+    implements Comparable<ModelElement>, Documentable, HasLocation {
   // TODO(jcollins-g): This really wants a "member that has a type" class.
   final Element? _originalMember;
   final Library _library;

lib/src/model/package.dart

@@ -30,7 +30,7 @@ const String htmlBasePlaceholder = r'%%__HTMLBASE_dartdoc_internal__%%';
 /// A [LibraryContainer] that contains [Library] objects related to a particular
 /// package.
 class Package extends LibraryContainer
-    with Nameable, Locatable, Warnable, CommentReferable {
+    with Nameable, Warnable, CommentReferable {
   @override
   final String name;
 
@@ -101,7 +101,7 @@ class Package extends LibraryContainer
   String? get belowSidebarPath => null;
 
   @override
-  List<Locatable> get documentationFrom => [this];
+  List<HasLocation> get documentationFrom => [this];
 
   /// Return true if the code has defined non-default categories for libraries
   /// in this package.

lib/src/model/package_graph.dart

@@ -388,7 +388,7 @@ class PackageGraph with CommentReferable, Nameable {
 
   void warnOnElement(Warnable? warnable, PackageWarning kind,
       {String? message,
-      Iterable<Locatable> referredFrom = const [],
+      Iterable<HasLocation> referredFrom = const [],
       Iterable<String> 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<Locatable> referredFrom = const [],
+      Iterable<HasLocation> referredFrom = const [],
       Iterable<String> extendedDebug = const []}) {
     if (warnable is ModelElement && kind == PackageWarning.ambiguousReexport) {
       // This sort of warning is only applicable to top level elements.

lib/src/validator.dart

@@ -236,7 +236,7 @@ class Validator {
     String origin, {
     String? referredFrom,
   }) {
-    final referredFromElements = <Locatable>{};
+    final referredFromElements = <HasLocation>{};
 
     // Make all paths relative to origin.
     if (path.isWithin(origin, warnOn)) {

lib/src/warnings.dart

@@ -94,20 +94,24 @@ List<DartdocOption<Object?>> createPackageWarningOptions(
 
 /// Something that package warnings can be reported on. Optionally associated
 /// with an analyzer [element].
-mixin Warnable implements CommentReferable, Documentable, Locatable {
+mixin Warnable implements CommentReferable, Documentable, HasLocation {
   Element? get element;
 
   void warn(
     PackageWarning kind, {
     String? message,
-    Iterable<Locatable> referredFrom = const [],
+    Iterable<HasLocation> referredFrom = const [],
     Iterable<String> extendedDebug = const [],
   }) {
     packageGraph.warnOnElement(this, kind,
         message: message,
         referredFrom: referredFrom,
         extendedDebug: extendedDebug);
   }
+
+  /// Whether [documentationFrom] contains only one item, `this`.
+  bool get documentationIsLocal =>
+      documentationFrom.length == 1 && identical(documentationFrom.first, this);
 }
 
 /// The kinds of warnings that can be displayed when documenting a package.
@@ -326,7 +330,7 @@ enum PackageWarning implements Comparable<PackageWarning> {
   String messageForWarnable(Warnable warnable) =>
       '$_warnablePrefix ${warnable.safeWarnableName}: ${warnable.location}';
 
-  String messageForReferral(Locatable referral) =>
+  String messageForReferral(HasLocation referral) =>
       '$_referredFromPrefix ${referral.safeWarnableName}: ${referral.location}';
 }