Remove Indexable as an unnecessary mixin. (dart-lang#3884)

This mixin only served as an interface providing `href` and `kind`, and
providing an impl for `overriddenDepth`. This amounted to a lot of complexity.
Some APIs were thus written in terms of Indexable. And any class that mixed in
Indexable gets an `overriddenDepth` property which is inapplicable, more often
than not.

As Documentable has `href` and `kind`, the easiest migration is to switch most
Indexable-concerned APIs to use Documentable. We move `overriddenDepth` to
_only_ be defined on Inheritable.

Author: srawlins

lib/dartdoc.dart

@@ -9,7 +9,7 @@ library;
 export 'package:dartdoc/src/dartdoc.dart';
 export 'package:dartdoc/src/dartdoc_options.dart';
 export 'package:dartdoc/src/generator/generator.dart';
-export 'package:dartdoc/src/model/indexable.dart' show Kind;
+export 'package:dartdoc/src/model/kind.dart';
 export 'package:dartdoc/src/model/package_builder.dart';
 export 'package:dartdoc/src/model/package_graph.dart';
 export 'package:dartdoc/src/package_config_provider.dart';

lib/src/generator/generator_backend.dart

@@ -105,7 +105,7 @@ abstract class GeneratorBackend {
   }
 
   /// Emits a JSON catalog of [indexedElements] for use with a search index.
-  void generateSearchIndex(List<Indexable> indexedElements) {
+  void generateSearchIndex(List<Documentable> indexedElements) {
     var json = generator_util.generateSearchIndexJson(
       indexedElements,
       packageOrder: options.packageOrder,

lib/src/generator/generator_frontend.dart

@@ -48,7 +48,7 @@ class GeneratorFrontEnd implements Generator {
 
   /// Traverses the [packageGraph] and generates documentation for all contained
   /// elements.
-  List<Indexable> _generateDocs(PackageGraph packageGraph) {
+  List<Documentable> _generateDocs(PackageGraph packageGraph) {
     runtimeStats.resetAccumulators({
       'writtenCategoryFileCount',
       'writtenClassFileCount',
@@ -69,7 +69,7 @@ class GeneratorFrontEnd implements Generator {
     _generatorBackend.generatePackage(
         packageGraph, packageGraph.defaultPackage);
 
-    var indexAccumulator = <Indexable>[];
+    var indexAccumulator = <Documentable>[];
     var multiplePackages = packageGraph.localPackages.length > 1;
 
     void generateConstants(Container container, Library library) {

lib/src/generator/generator_utils.dart

@@ -6,9 +6,11 @@ import 'dart:convert';
 
 import 'package:collection/collection.dart';
 import 'package:dartdoc/src/model/directives/categorization.dart';
-import 'package:dartdoc/src/model/indexable.dart';
+import 'package:dartdoc/src/model/documentable.dart';
+import 'package:dartdoc/src/model/inheritable.dart';
 import 'package:dartdoc/src/model/library.dart';
 import 'package:dartdoc/src/model/model_element.dart';
+import 'package:dartdoc/src/model/nameable.dart';
 
 String generateCategoryJson(Iterable<Categorization> categories, bool pretty) {
   final indexItems = [
@@ -37,7 +39,7 @@ String generateCategoryJson(Iterable<Categorization> categories, bool pretty) {
 /// [indexedElements] and [packageOrder].
 ///
 /// Passing `pretty: true` will use a [JsonEncoder] with a single-space indent.
-String generateSearchIndexJson(Iterable<Indexable> indexedElements,
+String generateSearchIndexJson(Iterable<Documentable> indexedElements,
     {required List<String> packageOrder, required bool pretty}) {
   var indexItems = <Map<String, Object?>>[];
 
@@ -52,8 +54,7 @@ String generateSearchIndexJson(Iterable<Indexable> indexedElements,
       'qualifiedName': element.canonicalQualifiedName,
       'href': element.href,
       'kind': element.kind.index,
-      // TODO(srawlins): Only include this for [Inheritable] items.
-      'overriddenDepth': element.overriddenDepth,
+      if (element is Inheritable) 'overriddenDepth': element.overriddenDepth,
     };
 
     if (element is ModelElement) {
@@ -131,7 +132,7 @@ final _htmlTagPattern =
     RegExp(r'<[^>]*>', multiLine: true, caseSensitive: true);
 
 // Compares two elements, first by fully qualified name, then by kind.
-int _compareElementRepresentations(Indexable a, Indexable b) {
+int _compareElementRepresentations(Documentable a, Documentable b) {
   final value =
       compareNatural(a.canonicalQualifiedName, b.canonicalQualifiedName);
   if (value == 0) {
@@ -140,7 +141,7 @@ int _compareElementRepresentations(Indexable a, Indexable b) {
   return value;
 }
 
-extension on Indexable {
+extension on Nameable {
   /// The fully qualified name of this element, but using the canonical library,
   /// if it has one.
   String get canonicalQualifiedName {

lib/src/generator/template_data.dart

@@ -5,6 +5,7 @@
 /// @docImport 'generator_backend.dart';
 library;
 
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 
 typedef ContainerSidebar = String Function(

lib/src/generator/templates.runtime_renderers.dart

@@ -841,7 +841,6 @@ class _Renderer_Category extends RendererBase<Category> {
                 ..._Renderer_MarkdownFileDocumentation.propertyMap<CT_>(),
                 ..._Renderer_LibraryContainer.propertyMap<CT_>(),
                 ..._Renderer_TopLevelContainer.propertyMap<CT_>(),
-                ..._Renderer_Indexable.propertyMap<CT_>(),
                 'aboveSidebarPath': Property(
                   getValue: (CT_ c) => c.aboveSidebarPath,
                   renderVariable:
@@ -6888,73 +6887,6 @@ class _Renderer_HasNoPage extends RendererBase<HasNoPage> {
   }
 }
 
-class _Renderer_Indexable extends RendererBase<Indexable> {
-  static final Map<Type, Object> _propertyMapCache = {};
-  static Map<String, Property<CT_>> propertyMap<CT_ extends Indexable>() =>
-      _propertyMapCache.putIfAbsent(
-          CT_,
-          () => {
-                'href': Property(
-                  getValue: (CT_ c) => c.href,
-                  renderVariable:
-                      (CT_ c, Property<CT_> self, List<String> remainingNames) {
-                    if (remainingNames.isEmpty) {
-                      return self.getValue(c).toString();
-                    }
-                    var name = remainingNames.first;
-                    var nextProperty =
-                        _Renderer_String.propertyMap().getValue(name);
-                    return nextProperty.renderVariable(
-                        self.getValue(c) as String,
-                        nextProperty,
-                        [...remainingNames.skip(1)]);
-                  },
-                  isNullValue: (CT_ c) => c.href == null,
-                  renderValue: (CT_ c, RendererBase<CT_> r,
-                      List<MustachioNode> ast, StringSink sink) {
-                    _render_String(c.href!, ast, r.template, sink, parent: r);
-                  },
-                ),
-                'kind': Property(
-                  getValue: (CT_ c) => c.kind,
-                  renderVariable: (CT_ c, Property<CT_> self,
-                          List<String> remainingNames) =>
-                      self.renderSimpleVariable(c, remainingNames, 'Kind'),
-                  isNullValue: (CT_ c) => false,
-                  renderValue: (CT_ c, RendererBase<CT_> r,
-                      List<MustachioNode> ast, StringSink sink) {
-                    renderSimple(c.kind, ast, r.template, sink,
-                        parent: r, getters: _invisibleGetters['Kind']!);
-                  },
-                ),
-                'overriddenDepth': Property(
-                  getValue: (CT_ c) => c.overriddenDepth,
-                  renderVariable: (CT_ c, Property<CT_> self,
-                          List<String> remainingNames) =>
-                      self.renderSimpleVariable(c, remainingNames, 'int'),
-                  isNullValue: (CT_ c) => c.overriddenDepth == null,
-                  renderValue: (CT_ c, RendererBase<CT_> r,
-                      List<MustachioNode> ast, StringSink sink) {
-                    renderSimple(c.overriddenDepth, ast, r.template, sink,
-                        parent: r, getters: _invisibleGetters['int']!);
-                  },
-                ),
-              }) as Map<String, Property<CT_>>;
-
-  _Renderer_Indexable(Indexable context, RendererBase<Object>? parent,
-      Template template, StringSink sink)
-      : super(context, parent, template, sink);
-
-  @override
-  Property<Indexable>? getProperty(String key) {
-    if (propertyMap<Indexable>().containsKey(key)) {
-      return propertyMap<Indexable>()[key];
-    } else {
-      return null;
-    }
-  }
-}
-
 class _Renderer_Inheritable extends RendererBase<Inheritable> {
   static final Map<Type, Object> _propertyMapCache = {};
   static Map<String, Property<CT_>> propertyMap<CT_ extends Inheritable>() =>
@@ -10072,7 +10004,6 @@ class _Renderer_ModelElement extends RendererBase<ModelElement> {
                 ..._Renderer_Locatable.propertyMap<CT_>(),
                 ..._Renderer_Nameable.propertyMap<CT_>(),
                 ..._Renderer_SourceCode.propertyMap<CT_>(),
-                ..._Renderer_Indexable.propertyMap<CT_>(),
                 ..._Renderer_FeatureSet.propertyMap<CT_>(),
                 ..._Renderer_DocumentationComment.propertyMap<CT_>(),
                 'annotations': Property(
@@ -12313,7 +12244,7 @@ class _Renderer_Package extends RendererBase<Package> {
   }
 }
 
-String renderIndex(PackageTemplateData context, Template template) {
+String renderSearchPage(PackageTemplateData context, Template template) {
   var buffer = StringBuffer();
   _render_PackageTemplateData(context, template.ast, template, buffer);
   return buffer.toString();
@@ -12551,13 +12482,13 @@ class _Renderer_PackageTemplateData extends RendererBase<PackageTemplateData> {
   }
 }
 
-String renderError(PackageTemplateData context, Template template) {
+String renderIndex(PackageTemplateData context, Template template) {
   var buffer = StringBuffer();
   _render_PackageTemplateData(context, template.ast, template, buffer);
   return buffer.toString();
 }
 
-String renderSearchPage(PackageTemplateData context, Template template) {
+String renderError(PackageTemplateData context, Template template) {
   var buffer = StringBuffer();
   _render_PackageTemplateData(context, template.ast, template, buffer);
   return buffer.toString();

lib/src/model/accessor.dart

@@ -11,6 +11,7 @@ import 'package:analyzer/src/dart/element/member.dart' show ExecutableMember;
 import 'package:collection/collection.dart' show IterableExtension;
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/utils.dart';
 import 'package:dartdoc/src/warnings.dart';

lib/src/model/category.dart

@@ -6,6 +6,7 @@ import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/warnings.dart';
 
@@ -18,8 +19,7 @@ class Category
         Locatable,
         MarkdownFileDocumentation,
         LibraryContainer,
-        TopLevelContainer,
-        Indexable
+        TopLevelContainer
     implements Documentable {
   /// The package in which this category is contained.
   ///

lib/src/model/class.dart

@@ -3,6 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analyzer/dart/element/element.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 
 /// A [Container] defined with a `class` declaration.

lib/src/model/constructor.dart

@@ -6,6 +6,7 @@ import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/source/line_info.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/model_utils.dart';
 

lib/src/model/directives/categorization.dart

@@ -9,7 +9,7 @@ final RegExp _categoryRegExp =
     RegExp(r'[ ]*{@(category|subCategory) (.+?)}[ ]*\n?', multiLine: true);
 
 /// Mixin parsing the `@category` directive for ModelElements.
-mixin Categorization on DocumentationComment implements Indexable {
+mixin Categorization on DocumentationComment {
   @override
   String buildDocumentationAddition(String rawDocs) =>
       _stripAndSetDartdocCategories(super.buildDocumentationAddition(rawDocs));

lib/src/model/documentable.dart

@@ -5,6 +5,7 @@
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 import 'package:dartdoc/src/io_utils.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/warnings.dart';
 
 import 'model.dart';
@@ -29,10 +30,11 @@ abstract class Documentable with Nameable {
 
   DartdocOptionContext get config;
 
-  String? get href;
-
+  /// A human-friendly name for the kind of element this is.
   Kind get kind;
 
+  String? get href;
+
   /// The full path of the sidebar for elements "above" this element.
   ///
   /// A `null` value indicates no content is displayed in the "above" sidebar.

lib/src/model/dynamic.dart

@@ -5,6 +5,7 @@
 import 'package:analyzer/dart/element/element.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 
 class Dynamic extends ModelElement with HasNoPage {

lib/src/model/enum.dart

@@ -4,6 +4,7 @@
 
 import 'package:analyzer/dart/analysis/features.dart';
 import 'package:analyzer/dart/element/element.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/model_utils.dart' as model_utils;
 import 'package:meta/meta.dart';

lib/src/model/extension.dart

@@ -7,6 +7,7 @@ import 'package:analyzer/dart/element/nullability_suffix.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/model_utils.dart';
 import 'package:meta/meta.dart';

lib/src/model/extension_type.dart

@@ -5,6 +5,7 @@
 import 'package:analyzer/dart/element/element.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:meta/meta.dart';
 

lib/src/model/field.dart

@@ -6,6 +6,7 @@ import 'dart:convert';
 
 import 'package:analyzer/dart/element/element.dart';
 import 'package:dartdoc/src/model/attribute.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 
 class Field extends ModelElement

lib/src/model/inheritable.dart

@@ -175,7 +175,10 @@ mixin Inheritable on ContainerMember {
     return isOverride;
   }();
 
-  @override
+  /// The depth of overrides at which this element lives.
+  ///
+  /// Just a count of how long the chain of this element's `overriddenElement`.
+  /// For use in ranking search results.
   int get overriddenDepth {
     var depth = 0;
     var e = this;

lib/src/model/indexable.dart renamed to lib/src/model/kind.dart

@@ -1,9 +1,7 @@
-// Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file
+// Copyright (c) 2024, 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';
-
 enum Kind {
   accessor,
   constant,
@@ -82,12 +80,3 @@ enum Kind {
         _ => throw ArgumentError('Unknown kind "$value"'),
       };
 }
-
-/// Something able to be indexed.
-mixin Indexable implements Nameable {
-  String? get href;
-
-  Kind get kind;
-
-  int? get overriddenDepth => 0;
-}

lib/src/model/library.dart

@@ -7,6 +7,7 @@ import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/scope.dart';
 import 'package:analyzer/source/line_info.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_meta.dart' show PackageMeta;
 import 'package:dartdoc/src/warnings.dart';

lib/src/model/method.dart

@@ -9,6 +9,7 @@ import 'package:analyzer/src/dart/element/member.dart' show ExecutableMember;
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/attribute.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 
 class Method extends ModelElement

lib/src/model/mixin.dart

@@ -6,6 +6,7 @@ import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:dartdoc/src/element_type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
+import 'package:dartdoc/src/model/kind.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/model_utils.dart' as model_utils;
 import 'package:dartdoc/src/special_elements.dart';

lib/src/model/model.dart

@@ -21,7 +21,6 @@ export 'extension_type.dart';
 export 'field.dart';
 export 'getter_setter_combo.dart';
 export 'has_no_page.dart';
-export 'indexable.dart';
 export 'inheritable.dart';
 export 'inheriting_container.dart';
 export 'library.dart';