Merge from main branch to NNBD

CHANGELOG.md

@@ -1,3 +1,15 @@
+## 4.0.0
+* BREAKING CHANGE: Refactors to support NNBD and adapt to new analyzer 
+  changes are technically semver breaking.   If you make extensive use of
+  the `documentationComment` getter on `ModelElement` or other deep
+  structural elements in dartdoc or custom templates, they could break
+  dependent code.  (#2819, #2818, #2817, #2806, #2798)
+* BREAKING CHANGE: Remove a large number of long-standing deprecated
+  symbols in dartdoc. (#2821)
+* Fix a problem where certain comment reference strings could
+  crash the parser. (#2813, #2808)
+* Fix an assert in canonicalization for enums. (#2812)
+
 ## 3.1.0
 * This version supports the Dart language feature constructor tearoffs,
   pending completion by other tools.

analysis_options.yaml

@@ -1,6 +1,6 @@
 # Change analysis_options.yaml and analysis_options_presubmit.yaml
 # together.
-include: package:pedantic/analysis_options.1.11.0.yaml
+include: package:lints/recommended.yaml
 
 analyzer:
   errors:
@@ -19,45 +19,19 @@ analyzer:
     - 'testing/test_package_export_error/**'
 linter:
   rules:
-    - always_declare_return_types
-    - avoid_dynamic_calls
-    - avoid_single_cascade_in_expression_statements
-    - avoid_unused_constructor_parameters
-    - annotate_overrides
-    - avoid_init_to_null
-    - directives_ordering
-    - no_adjacent_strings_in_list
-    - package_api_docs
-    - prefer_final_fields
-    - prefer_initializing_formals
-    - prefer_void_to_null
-    - slash_for_doc_comments
-    - type_annotate_public_apis
-    #    - unnecessary_brace_in_string_interps
+    always_declare_return_types: true
+    annotate_overrides: true
+    avoid_dynamic_calls: true
+    avoid_single_cascade_in_expression_statements: true
+    avoid_unused_constructor_parameters: true
+    avoid_init_to_null: true
+    directives_ordering: true
+    no_adjacent_strings_in_list: true
+    package_api_docs: true
+    prefer_final_fields: true
+    prefer_initializing_formals: true
+    prefer_void_to_null: true
+    slash_for_doc_comments: true
+    type_annotate_public_apis: true
     # Work in progress canonical score lints
-    - avoid_empty_else
-    - avoid_relative_lib_imports
-    - avoid_shadowing_type_parameters
-    - await_only_futures
-    - camel_case_extensions
-    - camel_case_types
-    - curly_braces_in_flow_control_structures
-    - empty_catches
-    - file_names
-    - hash_and_equals
-    - iterable_contains_unrelated_type
-    - list_remove_unrelated_type
-    - no_duplicate_case_values
-    #    - non_constant_identifier_names
-    - package_prefixed_library_names
-    - prefer_generic_function_type_aliases
-    - prefer_is_empty
-    - prefer_is_not_empty
-    - prefer_iterable_whereType
-    - prefer_typing_uninitialized_variables
-    - provide_deprecation_message
-    - unawaited_futures
-    - unnecessary_overrides
-    - unrelated_type_equality_checks
-    - valid_regexps
-    - void_checks
+    unawaited_futures: true

analysis_options_presubmit.yaml

@@ -1,6 +1,6 @@
 # Change analysis_options.yaml and analysis_options_presubmit.yaml
 # together.
-include: package:pedantic/analysis_options.1.11.0.yaml
+include: package:lints/recommended.yaml
 
 analyzer:
   errors:
@@ -24,45 +24,19 @@ analyzer:
     - 'testing/test_package_export_error/**'
 linter:
   rules:
-    - always_declare_return_types
-    - avoid_dynamic_calls
-    - avoid_single_cascade_in_expression_statements
-    - avoid_unused_constructor_parameters
-    - annotate_overrides
-    - avoid_init_to_null
-    - directives_ordering
-    - no_adjacent_strings_in_list
-    - package_api_docs
-    - prefer_final_fields
-    - prefer_initializing_formals
-    - prefer_void_to_null
-    - slash_for_doc_comments
-    - type_annotate_public_apis
-    #    - unnecessary_brace_in_string_interps
+    always_declare_return_types: true
+    annotate_overrides: true
+    avoid_dynamic_calls: true
+    avoid_single_cascade_in_expression_statements: true
+    avoid_unused_constructor_parameters: true
+    avoid_init_to_null: true
+    directives_ordering: true
+    no_adjacent_strings_in_list: true
+    package_api_docs: true
+    prefer_final_fields: true
+    prefer_initializing_formals: true
+    prefer_void_to_null: true
+    slash_for_doc_comments: true
+    type_annotate_public_apis: true
     # Work in progress canonical score lints
-    - avoid_empty_else
-    - avoid_relative_lib_imports
-    - avoid_shadowing_type_parameters
-    - await_only_futures
-    - camel_case_extensions
-    - camel_case_types
-    - curly_braces_in_flow_control_structures
-    - empty_catches
-    - file_names
-    - hash_and_equals
-    - iterable_contains_unrelated_type
-    - list_remove_unrelated_type
-    - no_duplicate_case_values
-    #    - non_constant_identifier_names
-    - package_prefixed_library_names
-    - prefer_generic_function_type_aliases
-    - prefer_is_empty
-    - prefer_is_not_empty
-    - prefer_iterable_whereType
-    - prefer_typing_uninitialized_variables
-    - provide_deprecation_message
-    - unawaited_futures
-    - unnecessary_overrides
-    - unrelated_type_equality_checks
-    - valid_regexps
-    - void_checks
+    unawaited_futures: true

dartdoc_options.yaml

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

lib/dartdoc.dart

@@ -6,8 +6,8 @@
 
 /// A documentation generator for Dart.
 ///
-/// Library interface is currently under heavy construction and may change
-/// drastically between minor revisions.
+/// Library interface is still experimental.
+@experimental
 library dartdoc;
 
 import 'dart:async';
@@ -372,7 +372,7 @@ class Dartdoc {
     var indexPath = path.joinAll([origin, 'index.html']);
     var file = config.resourceProvider.getFile(fullPath);
     if (!file.exists) {
-      return null;
+      return;
     }
     var decoder = JsonDecoder();
     List<Object> jsonData = decoder.convert(file.readAsStringSync());
@@ -417,7 +417,7 @@ class Dartdoc {
       // Remove so that we properly count that the file doesn't exist for
       // the orphan check.
       visited.remove(fullPath);
-      return null;
+      return;
     }
     visited.add(fullPath);
     var stringLinks = stringLinksAndHref.item1;

lib/src/comment_references/parser.dart

@@ -134,13 +134,12 @@ class CommentReferenceParser {
         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);
+        } else {
+          assert(typeVariablesResult.type ==
+              _TypeVariablesResultType.notTypeVariables);
         }
       }
       if (_atEnd || _thisChar != $dot) {

lib/src/dartdoc_options.dart

@@ -533,7 +533,9 @@ abstract class DartdocOption<T extends Object?> {
   /// Apply the function [visit] to [this] and all children.
   void traverse(void Function(DartdocOption option) visit) {
     visit(this);
-    _children.values.forEach((d) => d.traverse(visit));
+    for (var value in _children.values) {
+      value.traverse(visit);
+    }
   }
 }
 
@@ -716,7 +718,9 @@ class DartdocOptionRoot extends DartdocOptionSet {
   /// configuration object.
   @override
   void traverse(void Function(DartdocOption option) visitor) {
-    _children.values.forEach((d) => d.traverse(visitor));
+    for (var value in _children.values) {
+      value.traverse(visitor);
+    }
   }
 
   @override
@@ -732,7 +736,7 @@ class DartdocOptionSet extends DartdocOption<void> {
 
   /// [DartdocOptionSet] always has the null value.
   @override
-  void valueAt(Folder dir) => null;
+  void valueAt(Folder dir) {}
 
   /// Since we have no value, [_onMissing] does nothing.
   @override
@@ -995,7 +999,9 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {
         }
       }
     }
-    canonicalPaths.forEach((p) => _yamlAtCanonicalPathCache[p] = yamlData);
+    for (var canonicalPath in canonicalPaths) {
+      _yamlAtCanonicalPathCache[canonicalPath] = yamlData;
+    }
     return yamlData;
   }
 }
@@ -1102,7 +1108,7 @@ abstract class _DartdocArgOption<T> implements DartdocOption<T> {
   /// 'something-bar-over-the-hill' (with default skip).
   /// This allows argument names to reflect nested structure.
   static String _keysToArgName(Iterable<String> keys, [int skip = 1]) {
-    var argName = "${keys.skip(skip).join('-')}";
+    var argName = keys.skip(skip).join('-');
     argName = argName.replaceAll('_', '-');
     // Do not consume the lowercase character after the uppercase one, to handle
     // two character words.

lib/src/element_type.dart

@@ -12,11 +12,22 @@ import 'package:analyzer/dart/element/nullability_suffix.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:dartdoc/src/model/comment_referable.dart';
 import 'package:dartdoc/src/model/model.dart';
+import 'package:dartdoc/src/model/model_object_builder.dart';
 import 'package:dartdoc/src/render/element_type_renderer.dart';
 
+mixin ElementTypeBuilderImpl implements ElementTypeBuilder {
+  PackageGraph get packageGraph;
+
+  @override
+  ElementType typeFrom(DartType f, Library library,
+          {ElementType returnedFrom}) =>
+      ElementType._from(f, library, packageGraph, returnedFrom: returnedFrom);
+}
+
 /// Base class representing a type in Dartdoc.  It wraps a [DartType], and
 /// may link to a [ModelElement].
-abstract class ElementType extends Privacy with CommentReferable, Nameable {
+abstract class ElementType extends Privacy
+    with CommentReferable, Nameable, ModelBuilder {
   final DartType _type;
   @override
   final PackageGraph packageGraph;
@@ -26,7 +37,7 @@ abstract class ElementType extends Privacy with CommentReferable, Nameable {
 
   ElementType(this._type, this.library, this.packageGraph, this.returnedFrom);
 
-  factory ElementType.from(
+  factory ElementType._from(
       DartType f, Library library, PackageGraph packageGraph,
       {ElementType returnedFrom}) {
     if (f.element == null ||
@@ -41,7 +52,7 @@ abstract class ElementType extends Privacy with CommentReferable, Nameable {
       }
       return UndefinedElementType(f, library, packageGraph, returnedFrom);
     } else {
-      var element = ModelElement.fromElement(f.element, packageGraph);
+      var element = packageGraph.modelBuilder.fromElement(f.element);
       // [TypeAliasElement.aliasElement] has different implications.
       // In that case it is an actual type alias of some kind (generic
       // or otherwise.   Here however aliasElement signals that this is a
@@ -174,7 +185,7 @@ class FunctionTypeElementType extends UndefinedElementType
 
   /// An unmodifiable list of this function element's type parameters.
   List<TypeParameter> get typeFormals => type.typeFormals
-      .map((p) => ModelElement.from(p, library, packageGraph) as TypeParameter)
+      .map((p) => packageGraph.modelBuilder.from(p, library) as TypeParameter)
       .toList(growable: false);
 
   @override
@@ -215,26 +226,26 @@ class ParameterizedElementType extends DefinedElementType with Rendered {
   @override
   Iterable<ElementType> get typeArguments =>
       _typeArguments ??= type.typeArguments
-          .map((f) => ElementType.from(f, library, packageGraph))
+          .map((f) => modelBuilder.typeFrom(f, library))
           .toList(growable: false);
 }
 
 /// A [ElementType] whose underlying type was referrred to by a type alias.
-mixin Aliased implements ElementType {
+mixin Aliased implements ElementType, ModelBuilderInterface {
   @override
   String get name => type.alias.element.name;
 
   @override
   bool get isTypedef => true;
 
   ModelElement _aliasElement;
-  ModelElement get aliasElement => _aliasElement ??=
-      ModelElement.fromElement(type.alias.element, packageGraph);
+  ModelElement get aliasElement =>
+      _aliasElement ??= modelBuilder.fromElement(type.alias.element);
 
   Iterable<ElementType> _aliasArguments;
   Iterable<ElementType> get aliasArguments =>
       _aliasArguments ??= type.alias.typeArguments
-          .map((f) => ElementType.from(f, library, packageGraph))
+          .map((f) => modelBuilder.typeFrom(f, library))
           .toList(growable: false);
 }
 
@@ -376,12 +387,12 @@ abstract class DefinedElementType extends ElementType {
 /// unless it is an alias reference.
 mixin Callable implements ElementType {
   List<Parameter> get parameters => type.parameters
-      .map((p) => ModelElement.from(p, library, packageGraph) as Parameter)
+      .map((p) => modelBuilder.from(p, library) as Parameter)
       .toList(growable: false);
 
   ElementType _returnType;
   ElementType get returnType {
-    _returnType ??= ElementType.from(type.returnType, library, packageGraph);
+    _returnType ??= modelBuilder.typeFrom(type.returnType, library);
     return _returnType;
   }
 
@@ -432,7 +443,7 @@ class CallableElementType extends DefinedElementType with Rendered, Callable {
   @override
   Iterable<ElementType> get typeArguments =>
       _typeArguments ??= (type.alias?.typeArguments ?? [])
-          .map((f) => ElementType.from(f, library, packageGraph))
+          .map((f) => modelBuilder.typeFrom(f, library))
           .toList(growable: false);
 }
 

lib/src/experiment_options.dart

@@ -9,6 +9,7 @@
 library dartdoc.experiment_options;
 
 import 'package:analyzer/file_system/file_system.dart';
+// ignore: implementation_imports
 import 'package:analyzer/src/dart/analysis/experiments.dart';
 import 'package:dartdoc/src/dartdoc_options.dart';
 

lib/src/generator/empty_generator.dart

@@ -13,10 +13,10 @@ import 'package:dartdoc/src/model_utils.dart';
 /// it were.
 class EmptyGenerator extends Generator {
   @override
-  Future<void> generate(PackageGraph _packageGraph, FileWriter writer) {
-    logProgress(_packageGraph.defaultPackage.documentationAsHtml);
-    for (var package in {_packageGraph.defaultPackage}
-      ..addAll(_packageGraph.localPackages)) {
+  Future<void> generate(PackageGraph packageGraph, FileWriter writer) {
+    logProgress(packageGraph.defaultPackage.documentationAsHtml);
+    for (var package in {packageGraph.defaultPackage}
+      ..addAll(packageGraph.localPackages)) {
       for (var category in filterNonDocumented(package.categories)) {
         logProgress(category.documentationAsHtml);
       }

lib/src/generator/html_generator.dart

@@ -61,7 +61,7 @@ class HtmlGeneratorBackend extends DartdocGeneratorBackend {
   }
 
   Future<void> _copyResources(FileWriter writer) async {
-    for (var resourcePath in resources.resource_names) {
+    for (var resourcePath in resources.resourceNames) {
       if (!resourcePath.startsWith(_dartdocResourcePrefix)) {
         throw StateError('Resource paths must start with '
             '$_dartdocResourcePrefix, encountered $resourcePath');