Initial implementation of constructor tearoff support

Author: jcollins-g

lib/src/model/constructor.dart

@@ -67,9 +67,11 @@ class Constructor extends ModelElement
   @override
   bool get isConst => element.isConst;
 
-  bool get isUnnamedConstructor => name == enclosingElement.name;
+  bool get isUnnamedConstructor =>
+      name == enclosingElement.name || name == '${enclosingElement.name}.new';
 
   @Deprecated(
+      // TODO(jcollins-g): This, in retrospect, seems like a bad idea.
       'Renamed to `isUnnamedConstructor`; this getter with the old name will '
       'be removed as early as Dartdoc 1.0.0')
   bool get isDefaultConstructor => isUnnamedConstructor;
@@ -144,5 +146,5 @@ class Constructor extends ModelElement
 
   @override
   String get referenceName =>
-      element.name == '' ? enclosingElement.name : element.name;
+      isUnnamedConstructor ? enclosingElement.name : element.name;
 }

test/end2end/model_special_cases_test.dart

@@ -12,6 +12,7 @@ import 'dart:io';
 
 import 'package:analyzer/dart/element/type.dart';
 import 'package:async/async.dart';
+import 'package:dartdoc/src/matching_link_result.dart';
 import 'package:dartdoc/src/model/model.dart';
 import 'package:dartdoc/src/package_config_provider.dart';
 import 'package:dartdoc/src/package_meta.dart';
@@ -20,6 +21,7 @@ import 'package:pub_semver/pub_semver.dart';
 import 'package:test/test.dart';
 
 import '../src/utils.dart' as utils;
+import '../src/utils.dart';
 
 final _testPackageGraphExperimentsMemo = AsyncMemoizer<PackageGraph>();
 Future<PackageGraph> get _testPackageGraphExperiments =>
@@ -75,10 +77,107 @@ void main() {
       VersionRange(min: Version.parse('2.14.0-0'), includeMin: true);
   final _tripleShiftAllowed =
       VersionRange(min: Version.parse('2.14.0-0'), includeMin: true);
+  final _constructorTearoffsAllowed =
+      VersionRange(min: Version.parse('2.15.0-0'), includeMin: true);
 
   // Experimental features not yet enabled by default.  Move tests out of this
   // block when the feature is enabled by default.
   group('Experiments', () {
+    group('constructor-tearoffs', () {
+      Library constructorTearoffs;
+      Class A, B, C, D, E, F;
+      Mixin M;
+      Typedef At, Bt, Ct, Et, Ft, NotAClass;
+      Constructor Anew, Bnew, Cnew, Dnew, Enew, Fnew;
+
+      setUpAll(() async {
+        constructorTearoffs = (await _testPackageGraphExperiments)
+            .libraries
+            .firstWhere((l) => l.name == 'constructor_tearoffs');
+        A = constructorTearoffs.classes.firstWhere((c) => c.name == 'A');
+        B = constructorTearoffs.classes.firstWhere((c) => c.name == 'B');
+        C = constructorTearoffs.classes.firstWhere((c) => c.name == 'C');
+        D = constructorTearoffs.classes.firstWhere((c) => c.name == 'D');
+        E = constructorTearoffs.classes.firstWhere((c) => c.name == 'E');
+        F = constructorTearoffs.classes.firstWhere((c) => c.name == 'F');
+        M = constructorTearoffs.mixins.firstWhere((m) => m.name == 'M');
+        At = constructorTearoffs.typedefs.firstWhere((t) => t.name == 'At');
+        Bt = constructorTearoffs.typedefs.firstWhere((t) => t.name == 'Bt');
+        Ct = constructorTearoffs.typedefs.firstWhere((t) => t.name == 'Ct');
+        Et = constructorTearoffs.typedefs.firstWhere((t) => t.name == 'Et');
+        Ft = constructorTearoffs.typedefs.firstWhere((t) => t.name == 'Ft');
+        NotAClass = constructorTearoffs.typedefs
+            .firstWhere((t) => t.name == 'NotAClass');
+        Anew = A.unnamedConstructor;
+        Bnew = B.unnamedConstructor;
+        Cnew = C.unnamedConstructor;
+        Dnew = D.unnamedConstructor;
+        Enew = E.unnamedConstructor;
+        Fnew = F.unnamedConstructor;
+      });
+
+      test('smoke test', () {
+        expect(A, isNotNull);
+        expect(B, isNotNull);
+        expect(C, isNotNull);
+        expect(D, isNotNull);
+        expect(E, isNotNull);
+        expect(F, isNotNull);
+        expect(M, isNotNull);
+        expect(At, isNotNull);
+        expect(Bt, isNotNull);
+        expect(Ct, isNotNull);
+        expect(Et, isNotNull);
+        expect(Ft, isNotNull);
+        expect(NotAClass, isNotNull);
+        expect(Anew, isNotNull);
+        expect(Bnew, isNotNull);
+        expect(Cnew, isNotNull);
+        expect(Dnew, isNotNull);
+        expect(Enew, isNotNull);
+        expect(Fnew, isNotNull);
+      });
+
+      test('reference regression', () {
+        expect(newLookup(constructorTearoffs, 'A.A'),
+            equals(MatchingLinkResult(Anew)));
+        expect(newLookup(constructorTearoffs, 'new A()'),
+            equals(MatchingLinkResult(Anew)));
+        expect(newLookup(constructorTearoffs, 'A()'),
+            equals(MatchingLinkResult(Anew)));
+        expect(newLookup(constructorTearoffs, 'B.B'),
+            equals(MatchingLinkResult(Bnew)));
+        expect(newLookup(constructorTearoffs, 'new B()'),
+            equals(MatchingLinkResult(Bnew)));
+        expect(newLookup(constructorTearoffs, 'B()'),
+            equals(MatchingLinkResult(Bnew)));
+        expect(newLookup(constructorTearoffs, 'C.C'),
+            equals(MatchingLinkResult(Cnew)));
+        expect(newLookup(constructorTearoffs, 'new C()'),
+            equals(MatchingLinkResult(Cnew)));
+        expect(newLookup(constructorTearoffs, 'C()'),
+            equals(MatchingLinkResult(Cnew)));
+        expect(newLookup(constructorTearoffs, 'D.D'),
+            equals(MatchingLinkResult(Dnew)));
+        expect(newLookup(constructorTearoffs, 'new D()'),
+            equals(MatchingLinkResult(Dnew)));
+        expect(newLookup(constructorTearoffs, 'D()'),
+            equals(MatchingLinkResult(Dnew)));
+        expect(newLookup(constructorTearoffs, 'E.E'),
+            equals(MatchingLinkResult(Enew)));
+        expect(newLookup(constructorTearoffs, 'new E()'),
+            equals(MatchingLinkResult(Enew)));
+        expect(newLookup(constructorTearoffs, 'E()'),
+            equals(MatchingLinkResult(Enew)));
+        expect(newLookup(constructorTearoffs, 'F.F'),
+            equals(MatchingLinkResult(Fnew)));
+        expect(newLookup(constructorTearoffs, 'new F()'),
+            equals(MatchingLinkResult(Fnew)));
+        expect(newLookup(constructorTearoffs, 'F()'),
+            equals(MatchingLinkResult(Fnew)));
+      });
+    }, skip: !_constructorTearoffsAllowed.allows(utils.platformVersion));
+
     group('triple-shift', () {
       Library tripleShift;
       Class C, E, F;

test/end2end/model_test.dart

@@ -9,7 +9,6 @@ import 'dart:io';
 import 'package:analyzer/source/line_info.dart';
 import 'package:async/async.dart';
 import 'package:dartdoc/src/element_type.dart';
-import 'package:dartdoc/src/markdown_processor.dart';
 import 'package:dartdoc/src/matching_link_result.dart';
 import 'package:dartdoc/src/model/feature.dart';
 import 'package:dartdoc/src/model/model.dart';
@@ -25,6 +24,7 @@ import 'package:dartdoc/src/warnings.dart';
 import 'package:test/test.dart';
 
 import '../src/utils.dart' as utils;
+import '../src/utils.dart';
 
 final _testPackageGraphMemo = AsyncMemoizer<PackageGraph>();
 Future<PackageGraph> get testPackageGraph async =>
@@ -2124,35 +2124,6 @@ void main() {
   // Put linkage tests here; rendering tests should go to the appropriate
   // [Class], [Extension], etc groups.
   group('Comment References link tests', () {
-    /// For comparison purposes, return an equivalent [MatchingLinkResult]
-    /// for the defining element returned.  May return [originalResult].
-    /// We do this to eliminate canonicalization effects from comparison,
-    /// as the original lookup code returns canonicalized results and the
-    /// new lookup code is only guaranteed to return equivalent results.
-    MatchingLinkResult definingLinkResult(MatchingLinkResult originalResult) {
-      if (originalResult.commentReferable?.element != null) {
-        return MatchingLinkResult(
-            ModelElement.fromElement(originalResult.commentReferable.element,
-                originalResult.commentReferable.packageGraph),
-            warn: originalResult.warn);
-      }
-      return originalResult;
-    }
-
-    MatchingLinkResult originalLookup(Warnable element, String codeRef) =>
-        definingLinkResult(getMatchingLinkElement(element, codeRef,
-            enhancedReferenceLookup: false));
-    MatchingLinkResult newLookup(Warnable element, String codeRef) =>
-        definingLinkResult(getMatchingLinkElement(element, codeRef,
-            enhancedReferenceLookup: true));
-
-    MatchingLinkResult bothLookup(Warnable element, String codeRef) {
-      var originalLookupResult = originalLookup(element, codeRef);
-      var newLookupResult = newLookup(element, codeRef);
-      expect(newLookupResult.isEquivalentTo(originalLookupResult), isTrue);
-      return newLookupResult;
-    }
-
     group('Linking for generalized typedef cases works', () {
       Library generalizedTypedefs;
       Typedef T0, T2, T5, T8;

test/src/utils.dart

@@ -10,11 +10,16 @@ import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/file_system/memory_file_system.dart';
 import 'package:analyzer/src/test_utilities/mock_sdk.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
+import 'package:dartdoc/src/markdown_processor.dart';
+import 'package:dartdoc/src/matching_link_result.dart';
+import 'package:dartdoc/src/model/model_element.dart';
 import 'package:dartdoc/src/model/package_builder.dart';
 import 'package:dartdoc/src/model/package_graph.dart';
 import 'package:dartdoc/src/package_config_provider.dart';
 import 'package:dartdoc/src/package_meta.dart';
+import 'package:dartdoc/src/warnings.dart';
 import 'package:pub_semver/pub_semver.dart';
+import 'package:test/expect.dart';
 
 /// The number of public libraries in testing/test_package, minus 2 for
 /// the excluded libraries listed in the initializers for _testPackageGraphMemo
@@ -190,3 +195,32 @@ two:lib/
 
   return projectFolder;
 }
+
+/// For comparison purposes, return an equivalent [MatchingLinkResult]
+/// for the defining element returned.  May return [originalResult].
+/// We do this to eliminate canonicalization effects from comparison,
+/// as the original lookup code returns canonicalized results and the
+/// new lookup code is only guaranteed to return equivalent results.
+MatchingLinkResult definingLinkResult(MatchingLinkResult originalResult) {
+  if (originalResult.commentReferable?.element != null) {
+    return MatchingLinkResult(
+        ModelElement.fromElement(originalResult.commentReferable.element,
+            originalResult.commentReferable.packageGraph),
+        warn: originalResult.warn);
+  }
+  return originalResult;
+}
+
+MatchingLinkResult originalLookup(Warnable element, String codeRef) =>
+    definingLinkResult(getMatchingLinkElement(element, codeRef,
+        enhancedReferenceLookup: false));
+MatchingLinkResult newLookup(Warnable element, String codeRef) =>
+    definingLinkResult(getMatchingLinkElement(element, codeRef,
+        enhancedReferenceLookup: true));
+
+MatchingLinkResult bothLookup(Warnable element, String codeRef) {
+  var originalLookupResult = originalLookup(element, codeRef);
+  var newLookupResult = newLookup(element, codeRef);
+  expect(newLookupResult.isEquivalentTo(originalLookupResult), isTrue);
+  return newLookupResult;
+}

testing/test_package_experiments/analysis_options.yaml

@@ -5,3 +5,4 @@ analyzer:
     - nonfunction-type-aliases
     - triple-shift
     - generic-metadata
+    - constructor-tearoffs

testing/test_package_experiments/lib/constructor_tearoffs.dart

@@ -0,0 +1,61 @@
+// Copyright (c) 2021, 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.
+
+/// Exercise a number of constructor-tearoff related features inside dartdoc.
+///
+/// References to tearoffs should work at a top level too:
+///   [A.new], [B.new], [At.new], [Bt.new], [C], [C.new], [D.new],
+///
+library constructor_tearoffs;
+
+abstract class A {
+  final int number;
+  /// Even though this is abstract, dartdoc should still allow referring to
+  /// [A.new].
+  A.new(this.number);
+}
+
+class B extends A {
+  B.new() : super(5);
+}
+
+class C {}
+
+typedef At = A;
+typedef Bt = B;
+typedef Ct = C;
+
+/// [Dt.new] should be a thing.
+abstract class D<T extends String> {}
+
+typedef Dt = D;
+
+/// I refer to many things, including typedef constructor tearoffs [At.new],
+/// [Bt.new], [Ct.new], [Et.new].
+/// Don't forget about [E.new], [E.E], or [D<String>.new].
+class E extends D<String> {
+  final String aValue;
+  E.new(this.aValue) {}
+}
+
+typedef Et = E;
+
+/// Referring to [F<T>.new] and [F<Object>.new] should work fine.
+class F<T> {
+  F() {
+    print('I too am a valid constructor invocation with this feature.');
+  }
+}
+
+typedef Ft = F;
+
+/// Referring to [Fstring.new] should be fine.
+typedef Fstring = F<String>;
+
+/// Can't refer to `.new` here.
+typedef NotAClass = Function;
+
+/// Mixins don't have constructors either, so disallow `M.new`.
+mixin M<T> on C {
+}

testing/test_package_experiments/pubspec.yaml

@@ -1,5 +1,5 @@
 name: test_package_experiments
 version: 0.0.1
 environment:
-  sdk: '>=2.14.0-0 <3.0.0'
+  sdk: '>=2.15.0-0 <3.0.0'
 description: Experimental flags are tested here.