Merge pull request #2777 from jcollins-g/nnbd-mastermerge-0907

Merge head to NNBD branch

Author: jcollins-g

CHANGELOG.md

@@ -1,3 +1,14 @@
+## 3.0.0
+* BREAKING CHANGE: Refactor of Class, Enum, and Mixin types result in some
+  deleted interfaces in templates and a change in class hierarchy. (#2770)
+* The experimental 'constructor-tearoffs' feature has been partially
+  implemented in dartdoc and should work in simple cases. (#2655, #2770,
+  #2768, #2766, #2763).
+* BREAKING CHANGE: The old lookup code has been deleted, along with the
+  `--no-enhanced-reference-lookup` flag. (#2765)
+* Deprecated uses of pub have been removed. (#2764)
+* Some internal refactors to support NNBD migration.
+
 ## 2.0.0
 * BREAKING CHANGE: changes to dartdoc options API
   to prepare for NNBD migration (#2745, #2744).

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v2.0.0/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v3.0.0/%f%#L%l%'

lib/src/comment_references/parser.dart

@@ -96,7 +96,7 @@ class CommentReferenceParser {
   /// ```text
   ///   <rawCommentReference> ::= <prefix>?<commentReference><suffix>?
   ///
-  ///   <commentReference> ::= (<packageName> '.')? (<libraryName> '.')? <dartdocIdentifier> ('.' <identifier>)*
+  ///   <commentReference> ::= (<packageName> '.')? (<libraryName> '.')? <dartdocIdentifier> <typeArguments> ('.' <identifier> <typeArguments>)*
   /// ```
   List<CommentReferenceNode> _parseRawCommentReference() {
     var children = <CommentReferenceNode>[];
@@ -124,6 +124,17 @@ class CommentReferenceParser {
       } else if (identifierResult.type ==
           _IdentifierResultType.parsedIdentifier) {
         children.add(identifierResult.node);
+        var typeVariablesResult = _parseTypeVariables();
+        if (typeVariablesResult.type == _TypeVariablesResultType.endOfFile) {
+          break;
+        } else if (typeVariablesResult.type ==
+            _TypeVariablesResultType.notTypeVariables) {
+          // Do nothing, _index has not moved.
+          ;
+        } else if (typeVariablesResult.type ==
+            _TypeVariablesResultType.parsedTypeVariables) {
+          children.add(typeVariablesResult.node);
+        }
       }
       if (_atEnd || _thisChar != $dot) {
         break;
@@ -239,6 +250,22 @@ class CommentReferenceParser {
         IdentifierNode(codeRef.substring(startIndex, _index)));
   }
 
+  /// Parse a list of type variables (arguments or parameters).
+  ///
+  /// Dartdoc isolates these where present and potentially valid, but we don't
+  /// break them down.
+  _TypeVariablesParseResult _parseTypeVariables() {
+    if (_atEnd) {
+      return _TypeVariablesParseResult.endOfFile;
+    }
+    var startIndex = _index;
+    if (_matchBraces($lt, $gt)) {
+      return _TypeVariablesParseResult.ok(
+          TypeVariablesNode(codeRef.substring(startIndex + 1, _index - 1)));
+    }
+    return _TypeVariablesParseResult.notIdentifier;
+  }
+
   static const _callableHintSuffix = '()';
 
   /// ```text
@@ -270,7 +297,7 @@ class CommentReferenceParser {
     if ((_thisChar == $exclamation || _thisChar == $question) && _nextAtEnd) {
       return _SuffixParseResult.junk;
     }
-    if (_matchBraces($lparen, $rparen) || _matchBraces($lt, $gt)) {
+    if (_matchBraces($lparen, $rparen)) {
       return _SuffixParseResult.junk;
     }
 
@@ -334,8 +361,10 @@ class CommentReferenceParser {
     while (!_atEnd) {
       if (_thisChar == startChar) braceCount++;
       if (_thisChar == endChar) braceCount--;
-      ++_index;
-      if (braceCount == 0) return true;
+      _index++;
+      if (braceCount == 0) {
+        return true;
+      }
     }
     _index = startIndex;
     return false;
@@ -395,6 +424,32 @@ class _IdentifierParseResult {
       _IdentifierParseResult._(_IdentifierResultType.notIdentifier, null);
 }
 
+enum _TypeVariablesResultType {
+  endOfFile, // Found end of file instead of the beginning of a list of type
+  // variables.
+  notTypeVariables, // Found something, but it isn't type variables.
+  parsedTypeVariables, // Found type variables.
+}
+
+class _TypeVariablesParseResult {
+  final _TypeVariablesResultType type;
+
+  final TypeVariablesNode node;
+
+  const _TypeVariablesParseResult._(this.type, this.node);
+
+  factory _TypeVariablesParseResult.ok(TypeVariablesNode node) =>
+      _TypeVariablesParseResult._(
+          _TypeVariablesResultType.parsedTypeVariables, node);
+
+  static const _TypeVariablesParseResult endOfFile =
+      _TypeVariablesParseResult._(_TypeVariablesResultType.endOfFile, null);
+
+  static const _TypeVariablesParseResult notIdentifier =
+      _TypeVariablesParseResult._(
+          _TypeVariablesResultType.notTypeVariables, null);
+}
+
 enum _SuffixResultType {
   junk, // Found known types of junk it is OK to ignore.
   missing, // There is no suffix here.  Same as EOF as this is a suffix.
@@ -459,3 +514,19 @@ class IdentifierNode extends CommentReferenceNode {
   @override
   String toString() => 'Identifier["$text"]';
 }
+
+/// Represents one or more type variables, may be
+/// comma separated.
+class TypeVariablesNode extends CommentReferenceNode {
+  @override
+
+  /// Note that this will contain commas, spaces, and other text, as
+  /// generally type variables are a form of junk that comment references
+  /// should ignore.
+  final String text;
+
+  TypeVariablesNode(this.text);
+
+  @override
+  String toString() => 'TypeVariablesNode["$text"]';
+}

lib/src/generator/generator_frontend.dart

@@ -170,14 +170,6 @@ class GeneratorFrontEnd implements Generator {
           indexAccumulator.add(mixin);
           _generatorBackend.generateMixin(writer, packageGraph, lib, mixin);
 
-          for (var constructor in filterNonDocumented(mixin.constructors)) {
-            if (!constructor.isCanonical) continue;
-
-            indexAccumulator.add(constructor);
-            _generatorBackend.generateConstructor(
-                writer, packageGraph, lib, mixin, constructor);
-          }
-
           for (var constant in filterNonDocumented(mixin.constantFields)) {
             if (!constant.isCanonical) continue;
             indexAccumulator.add(constant);

lib/src/generator/template_data.dart

@@ -175,34 +175,51 @@ class LibraryTemplateData extends TemplateData<Library>
 }
 
 /// Template data for Dart 2.1-style mixin declarations.
-class MixinTemplateData extends ClassTemplateData<Mixin> {
-  final Mixin mixin;
-
+class MixinTemplateData extends InheritingContainerTemplateData<Mixin> {
   MixinTemplateData(
       TemplateOptions htmlOptions,
       PackageGraph packageGraph,
       Library library,
-      this.mixin,
+      Mixin mixin,
       LibrarySidebar _sidebarForLibrary,
       ContainerSidebar _sidebarForContainer)
       : super(htmlOptions, packageGraph, library, mixin, _sidebarForLibrary,
             _sidebarForContainer);
 
+  Mixin get mixin => clazz;
+
   @override
   Mixin get self => mixin;
 }
 
+/// Template data for Dart classes.
+class ClassTemplateData extends InheritingContainerTemplateData<Class> {
+  ClassTemplateData(
+      TemplateOptions htmlOptions,
+      PackageGraph packageGraph,
+      Library library,
+      Class clazz,
+      LibrarySidebar _sidebarForLibrary,
+      ContainerSidebar _sidebarForContainer)
+      : super(htmlOptions, packageGraph, library, clazz, _sidebarForLibrary,
+            _sidebarForContainer);
+
+  @override
+  Class get clazz => super.clazz;
+}
+
 /// Base template data class for [Class], [Enum], and [Mixin].
-class ClassTemplateData<T extends Class> extends TemplateData<T>
+abstract class InheritingContainerTemplateData<T extends InheritingContainer>
+    extends TemplateData<T>
     implements TemplateDataWithLibrary<T>, TemplateDataWithContainer<T> {
-  final Class clazz;
+  final InheritingContainer clazz;
   @override
   final Library library;
   Class _objectType;
   final LibrarySidebar _sidebarForLibrary;
   final ContainerSidebar _sidebarForContainer;
 
-  ClassTemplateData(
+  InheritingContainerTemplateData(
       TemplateOptions htmlOptions,
       PackageGraph packageGraph,
       this.library,
@@ -337,7 +354,7 @@ class ConstructorTemplateData extends TemplateData<Constructor>
       'for the Dart programming language.';
 }
 
-class EnumTemplateData extends ClassTemplateData<Enum> {
+class EnumTemplateData extends InheritingContainerTemplateData<Enum> {
   EnumTemplateData(
       TemplateOptions htmlOptions,
       PackageGraph packageGraph,