Refactor Locatable into an interface, HasLocation (#4118)

Since the `mixin` was introduced, and the class modifiers, we've had
some tech debt around our mixins. We have a lot of mixins, and some of
them are better suited as interfaces or base classes. In this case,
`Locatable` was a mixin with mostly abstract getters, and one
implemented getter. To me this really smelled like it should be an
interface.

Turns out, that implemented getter, `documentationIsLocal`, is only
called on `Warnable` objects (which implemented `Locatable`). So we can
move the getter to `Warnable`.

Then we can change every case of `with Locatable` to `implements
Locatable`. _Except_ that the interface isn't even needed on some
classes, like `Category` and `Package`, so we can just remove the mixin
there.

Then a rename. I think it's idiomatic for mixin names to end in "able"
like "Locatable," "Warnable," "Namable" to suggest the ability that is
mixed in. And it is more idiomatic for an interface to start with "Has"
to suggest features that are implemented by an implementing class. But
there's nothing hard-and-fast here; I'm open to other naming ideas.

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}';
 }