Merge HasLocation into Warnable

Author: srawlins

lib/src/model/accessor.dart

@@ -104,7 +104,7 @@ class Accessor extends ModelElement {
   void warn(
     PackageWarning kind, {
     String? message,
-    Iterable<HasLocation> referredFrom = const [],
+    Iterable<Warnable> referredFrom = const [],
     Iterable<String> extendedDebug = const [],
   }) {
     enclosingCombo.warn(kind,

lib/src/model/category.dart

@@ -92,7 +92,7 @@ final class Category extends LibraryContainer
   PackageGraph get packageGraph => package.packageGraph;
 
   @override
-  List<HasLocation> get documentationFrom => [this];
+  List<Warnable> get documentationFrom => [this];
 
   @override
   DocumentLocation get documentedWhere => package.documentedWhere;

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'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
 ///
 /// [_processCommentWithoutTools] and [processComment] are the primary
 /// entrypoints.
-mixin DocumentationComment
-    implements Documentable, Warnable, HasLocation, SourceCode {
+mixin DocumentationComment implements Documentable, Warnable, SourceCode {
   @override
   Element get element;
 

lib/src/model/locatable.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';

lib/src/model/model.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<ModelElement>, Documentable, HasLocation {
+    implements Comparable<ModelElement>, Documentable {
   // TODO(jcollins-g): This really wants a "member that has a type" class.
   final Element? _originalMember;
   final Library _library;

lib/src/model/model_element.dart

@@ -104,7 +104,7 @@ final class Package extends LibraryContainer
   String? get belowSidebarPath => null;
 
   @override
-  List<HasLocation> get documentationFrom => [this];
+  List<Warnable> get documentationFrom => [this];
 
   /// Return true if the code has defined non-default categories for libraries
   /// in this package.

lib/src/model/package.dart

@@ -388,7 +388,7 @@ class PackageGraph with CommentReferable, Nameable {
 
   void warnOnElement(Warnable? warnable, PackageWarning kind,
       {String? message,
-      Iterable<HasLocation> referredFrom = const [],
+      Iterable<Warnable> 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<HasLocation> referredFrom = const [],
+      Iterable<Warnable> referredFrom = const [],
       Iterable<String> extendedDebug = const []}) {
     if (warnable is ModelElement && kind == PackageWarning.ambiguousReexport) {
       // This sort of warning is only applicable to top level elements.
@@ -468,7 +468,7 @@ class PackageGraph with CommentReferable, Nameable {
       warningMessage,
       if (warnable != null) kind.messageForWarnable(warnable),
       for (var referral in referredFrom)
-        if (referral != warnable) kind.messageForReferral(referral),
+        if (referral != warnable) kind.messageForWarnable(referral),
       if (config.verboseWarnings) ...extendedDebug.map((s) => '    $s')
     ].join('\n    ');
 

lib/src/model/package_graph.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 = <HasLocation>{};
+    final referredFromElements = <Warnable>{};
 
     // Make all paths relative to origin.
     if (path.isWithin(origin, warnOn)) {

lib/src/validator.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<DartdocOption<Object?>> 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<HasLocation> referredFrom = const [],
+    Iterable<Warnable> referredFrom = const [],
     Iterable<String> 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<Warnable> 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<PackageWarning> {
   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<PackageWarning, int> {
     }
   }
 }
+
+extension NullableWarnableExtension on Warnable? {
+  String get safeWarnableName =>
+      this?.fullyQualifiedName.replaceFirst(':', '-') ?? '<unknown>';
+}