Rank parent class method higher than its overrides in search suggestions (#1308)

We do that by saving `overriddenDepth` to index.json (which is just
how many overridden elements in the inheritance chain that element has),
and then reducing weight of elements in the suggestions according to
`overriddenDepth`.

Also, fixed `grind update-test-package-docs`, it didn't know where to
find examples for `@examples` directives.

Fixes #896

Author: astashov

lib/resources/script.js

@@ -76,6 +76,7 @@ function initSearch() {
     var allMatches = []; // list of matches
 
     function score(element, num) {
+      num -= element.overriddenDepth * 10;
       var weightFactor = weights[element.type] || 4;
       return {e: element, score: (num / weightFactor) >> 0};
     }

lib/src/html/html_generator_instance.dart

@@ -55,7 +55,8 @@ class HtmlGeneratorInstance implements HtmlOptions {
         'name': e.name,
         'qualifiedName': e.name,
         'href': e.href,
-        'type': e.kind
+        'type': e.kind,
+        'overriddenDepth': e.overriddenDepth,
       };
       if (e is EnclosedElement) {
         EnclosedElement ee = e as EnclosedElement;

lib/src/model.dart

@@ -1529,6 +1529,19 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
 
   ModelElement get overriddenElement => null;
 
+  int _overriddenDepth;
+  int get overriddenDepth {
+    if (_overriddenDepth == null) {
+      _overriddenDepth = 0;
+      ModelElement e = this;
+      while (e.overriddenElement != null) {
+        _overriddenDepth += 1;
+        e = e.overriddenElement;
+      }
+    }
+    return _overriddenDepth;
+  }
+
   Package get package =>
       (this is Library) ? (this as Library).package : this.library.package;
 

test/model_test.dart

@@ -911,6 +911,12 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
       expect(abstractMethod.fullkind, 'abstract method');
     });
 
+    test("returns correct overriddenDepth", () {
+      final bAbstractMethod = classB.allInstanceMethods.firstWhere((m) => m.name == "abstractMethod");
+      expect(abstractMethod.overriddenDepth, equals(0));
+      expect(bAbstractMethod.overriddenDepth, equals(1));
+    });
+
     test(
         'an inherited method has class as the enclosing class, when superclass not in package',
         () {

testing/test_package_docs/index.json

@@ -76,6 +76,7 @@ function initSearch() {
     var allMatches = []; // list of matches
 
     function score(element, num) {
+      num -= element.overriddenDepth * 10;
       var weightFactor = weights[element.type] || 4;
       return {e: element, score: (num / weightFactor) >> 0};
     }

testing/test_package_docs/static-assets/script.js

@@ -202,7 +202,7 @@ updateTestPackageDocs() {
   var options = new RunOptions(workingDirectory: 'testing/test_package');
   delete(getDir('test_package_docs'));
   Dart.run('../../bin/dartdoc.dart',
-      arguments: ['--no-include-source', '--output', '../test_package_docs'],
+      arguments: ['--no-include-source', '--output', '../test_package_docs', '--example-path-prefix', 'examples'],
       runOptions: options);
 }