Merge main branch to NNBD (#2826)

* Refactor more documentation comment generation into DocumentationComment (#2817)

* Straight move

* Partial

* delete experiment

* rebuild

* remove ??= from a cut and paste

* Continuing the crushing down of documentation handling (#2818)

* Straight move

* Partial

* delete experiment

* rebuild

* moved computeDocumentationComment and documentationComment

* Move more documentation comment handling

* remove ??= from a cut and paste

* Documentation comment move for combos

* better as a getter

* Remove all deprecated bits in preparation for next release (#2821)

* Remove all deprecated bits in preparation for next release

* make some things final

* documentationComment can now be non-nullable (#2819)

* Straight move

* Partial

* delete experiment

* rebuild

* moved computeDocumentationComment and documentationComment

* Move more documentation comment handling

* remove ??= from a cut and paste

* Documentation comment move for combos

* better as a getter

* Untangle synthetic combo documentation in preparing for non-null

* rebuild

* documentationComment can be made non-nullable

* Update test.yaml to delete sdk check from beta branch

* tab conversion error

* correct name

* Stop testing beta in the bots (#2824)

* disable beta

* try switching on stable

* stable doesn't work for a lot of things now either :-(

* try enabling the main bot

* Change "dartfmt" -> "dart format". (#2822)

Co-authored-by: Janice Collins <[email protected]>

Co-authored-by: Bob Nystrom <[email protected]>

Author: jcollins-g

.github/workflows/test.yaml

@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        sdk: [dev, beta]
+        sdk: [dev, stable]
         job: [nnbd, flutter, sdk-analyzer, packages, sdk-docs]
         include:
           - os: macos-latest
@@ -32,10 +32,12 @@ jobs:
             # Do not try to run flutter against the "stable" sdk,
             # it is unlikely to work and produces uninteresting
             # results.
-          - sdk: beta
+          - sdk: stable
             job: flutter
-          - sdk: beta
+          - sdk: stable
             job: sdk-analyzer
+          - sdk: stable
+            job: sdk-docs
 
     steps:
       - name: Store date

CONTRIBUTING.md

@@ -24,7 +24,7 @@ yet in the issue tracker, start by opening an issue. Thanks!
 2. When a change is user-facing, please add a new entry to the [changelog](https://github.com/dart-lang/dartdoc/blob/master/CHANGELOG.md)
 3. Please include a test for your change.  `dartdoc` has both `package:test`-style unittests as well as integration tests.  To run the unittests, use `grind test`.
 4. For major changes, run `grind compare-sdk-warnings` and `grind compare-flutter-warnings`, and include the summary results in your pull request.
-5. Be sure to format your Dart code using `dartfmt -w`, otherwise travis will complain.
+5. Be sure to format your Dart code using `dart format`, otherwise travis will complain.
 6. Use `grind presubmit` before creating a pull request to quickly check for common problems.
 7. Post your change via a pull request for review and integration!
 

lib/dartdoc.dart

@@ -143,20 +143,6 @@ class Dartdoc {
   // ignore: unnecessary_getters_setters
   set generator(Generator newGenerator) => _generator = newGenerator;
 
-  /// An asynchronous factory method that builds Dartdoc's file writers
-  /// and returns a Dartdoc object with them.
-  @Deprecated('Prefer fromContext() instead')
-  static Future<Dartdoc> withDefaultGenerators(
-    DartdocGeneratorOptionContext config,
-    PackageBuilder packageBuilder,
-  ) async {
-    return Dartdoc._(
-      config,
-      await initHtmlGenerator(config),
-      packageBuilder,
-    );
-  }
-
   /// Asynchronous factory method that builds Dartdoc with an empty generator.
   static Future<Dartdoc> withEmptyGenerator(
     DartdocOptionContext config,
@@ -195,15 +181,10 @@ class Dartdoc {
 
   Stream<String> get onCheckProgress => _onCheckProgress.stream;
 
-  @Deprecated('Will be removed in 4.0.0. '
-      'Use the return value from generateDocsBase instead.')
-  PackageGraph packageGraph;
-
   @visibleForTesting
   Future<DartdocResults> generateDocsBase() async {
     var stopwatch = Stopwatch()..start();
     var packageGraph = await packageBuilder.buildPackageGraph();
-    this.packageGraph = packageGraph;
     var seconds = stopwatch.elapsedMilliseconds / 1000.0;
     var libs = packageGraph.libraries.length;
     logInfo("Initialized dartdoc with $libs librar${libs == 1 ? 'y' : 'ies'} "

lib/src/generator/templates.runtime_renderers.dart

@@ -106,17 +106,6 @@ String getFileNameFor(String name) =>
     '${name.replaceAll(_libraryNameRegExp, '-')}.html';
 
 final _libraryNameRegExp = RegExp('[.:]');
-@Deprecated('Public variable intended to be private; will be removed as early '
-    'as Dartdoc 1.0.0')
-RegExp get libraryNameRegexp => _libraryNameRegExp;
-
-@Deprecated('Public variable intended to be private; will be removed as early '
-    'as Dartdoc 1.0.0')
-final RegExp partOfRegexp = RegExp('part of ');
-
-@Deprecated('Public variable intended to be private; will be removed as early '
-    'as Dartdoc 1.0.0')
-final RegExp newLinePartOfRegexp = RegExp('\npart of ');
 
 typedef TaskQueueClosure<T> = Future<T> Function();
 

lib/src/io_utils.dart

@@ -74,31 +74,57 @@ class Accessor extends ModelElement implements EnclosedElement {
     return _sourceCode;
   }
 
+  bool _documentationCommentComputed = false;
+  String _documentationComment;
   @override
-  String computeDocumentationComment() {
-    String docComment;
-    if (isSynthetic) {
-      // If we're a setter, only display something if we have something different than the getter.
-      // TODO(jcollins-g): modify analyzer to do this itself?
-      if (isGetter ||
-          definingCombo.hasNodoc ||
-          (isSetter &&
-              definingCombo.hasGetter &&
-              definingCombo.getter.documentationComment !=
-                  definingCombo.documentationComment)) {
-        docComment = definingCombo.documentationComment;
-      } else {
-        docComment = '';
+  String get documentationComment => _documentationCommentComputed
+      ? _documentationComment
+      : _documentationComment ??= () {
+          _documentationCommentComputed = true;
+          if (isSynthetic) {
+            return _syntheticDocumentationComment;
+          }
+          return stripComments(super.documentationComment);
+        }();
+
+  String /*!*/ __syntheticDocumentationComment;
+
+  /// Build a documentation comment for this accessor assuming it is synthetic.
+  /// Value here is not useful if [isSynthetic] is false.
+  String /*!*/ get _syntheticDocumentationComment =>
+      __syntheticDocumentationComment ??= () {
+        if (_hasSyntheticDocumentationComment) {
+          return definingCombo.documentationComment ?? '';
+        }
+        return '';
+      }();
+
+  /// If this is a getter, assume we want synthetic documentation.
+  /// If the definingCombo has a nodoc tag, we want synthetic documentation
+  /// for a synthetic accessor just in case it is inherited somewhere
+  /// down the line due to split inheritance.
+  bool get _hasSyntheticDocumentationComment =>
+      (isGetter || definingCombo.hasNodoc || _comboDocsAreIndependent()) &&
+      definingCombo.hasDocumentationComment;
+
+  // If we're a setter, and a getter exists, do not add synthetic
+  // documentation if the combo's documentation is actually derived
+  // from that getter.
+  bool _comboDocsAreIndependent() {
+    if (isSetter && definingCombo.hasGetter) {
+      if (definingCombo.getter.isSynthetic ||
+          !definingCombo.documentationFrom.contains(this)) {
+        return true;
       }
-    } else {
-      docComment = super.computeDocumentationComment();
-    }
-    if (docComment != null) {
-      return stripComments(docComment);
     }
-    return null;
+    return false;
   }
 
+  @override
+  bool get hasDocumentationComment => isSynthetic
+      ? _hasSyntheticDocumentationComment
+      : element.documentationComment != null;
+
   @override
   void warn(
     PackageWarning kind, {

lib/src/model/accessor.dart

@@ -28,7 +28,7 @@ abstract class Canonicalization implements Locatable, Documentable {
   }
 
   ScoredCandidate _scoreElementWithLibrary(Library lib) {
-    var scoredCandidate = ScoredCandidate(this, lib);
+    var scoredCandidate = ScoredCandidate(lib);
     Iterable<String> resplit(Set<String> items) sync* {
       for (var item in items) {
         for (var subItem in item.split('_')) {
@@ -72,44 +72,20 @@ abstract class Canonicalization implements Locatable, Documentable {
         scoreBoost, 'element location parts start with parts of name');
     return scoredCandidate;
   }
-
-  @Deprecated(
-      'Public method intended to be private; will be removed as early as '
-      'Dartdoc 1.0.0')
-  ScoredCandidate scoreElementWithLibrary(Library lib) =>
-      _scoreElementWithLibrary(lib);
 }
 
 /// This class represents the score for a particular element; how likely
 /// it is that this is the canonical element.
 class ScoredCandidate implements Comparable<ScoredCandidate> {
   final List<String> _reasons = [];
 
-  @Deprecated(
-      'Public field intended to be private; will be removed as early as '
-      'Dartdoc 1.0.0')
-  List<String> get reasons => _reasons;
-
-  @Deprecated(
-      'Public field intended to be private; will be removed as early as '
-      'Dartdoc 1.0.0')
-  set reasons(List<String> value) => reasons = value;
-
-  /// The canonicalization element being scored.
-  final Canonicalization _element;
-
-  @Deprecated(
-      'Public getter intended to be private; will be removed as early as '
-      'Dartdoc 1.0.0')
-  Canonicalization get element => _element;
-
   final Library library;
 
   /// The score accumulated so far.  Higher means it is more likely that this
   /// is the intended canonical Library.
   double score = 0.0;
 
-  ScoredCandidate(this._element, this.library);
+  ScoredCandidate(this.library);
 
   void _alterScore(double scoreDelta, String reason) {
     score += scoreDelta;
@@ -119,12 +95,6 @@ class ScoredCandidate implements Comparable<ScoredCandidate> {
     }
   }
 
-  @Deprecated(
-      'Public method intended to be private; will be removed as early as '
-      'Dartdoc 1.0.0')
-  void alterScore(double scoreDelta, String reason) =>
-      _alterScore(scoreDelta, reason);
-
   @override
   int compareTo(ScoredCandidate other) {
     //assert(element == other.element);

lib/src/model/canonicalization.dart

@@ -10,10 +10,6 @@ final RegExp _categoryRegExp = RegExp(
     r'[ ]*{@(api|category|subCategory|image|samples) (.+?)}[ ]*\n?',
     multiLine: true);
 
-@Deprecated('Public variable intended to be private; will be removed as early '
-    'as Dartdoc 1.0.0')
-RegExp get categoryRegexp => _categoryRegExp;
-
 /// Mixin implementing dartdoc categorization for ModelElements.
 abstract class Categorization implements ModelElement {
   @override

lib/src/model/categorization.dart

@@ -27,30 +27,18 @@ class Category extends Nameable
         Indexable
     implements Documentable {
   /// All libraries in [libraries] must come from [package].
-  // TODO(srawlins): To make final, remove public getter, setter, rename to be
-  // public, and add `final` modifier.
-  Package _package;
+  final Package _package;
 
   @override
   Package get package => _package;
 
-  @Deprecated('Field intended to be final; setter will be removed as early as '
-      'Dartdoc 1.0.0')
-  set package(Package value) => _package = value;
-
   final String _name;
 
-  // TODO(srawlins): To make final, remove public getter, setter, rename to be
-  // public, and add `final` modifier.
-  DartdocOptionContext _config;
+  final DartdocOptionContext _config;
 
   @override
   DartdocOptionContext get config => _config;
 
-  @Deprecated('Field intended to be final; setter will be removed as early as '
-      'Dartdoc 1.0.0')
-  set config(DartdocOptionContext value) => _config = value;
-
   final Set<Categorization> _allItems = {};
 
   final List<Class> _classes = [];
@@ -142,11 +130,6 @@ class Category extends Nameable
 
   String get _fileType => package.fileType;
 
-  @Deprecated(
-      'Public field intended to be private; will be removed as early as '
-      'Dartdoc 1.0.0')
-  String get fileType => _fileType;
-
   String get filePath => 'topics/$name-topic.$_fileType';
 
   @override

lib/src/model/category.dart

@@ -75,7 +75,7 @@ mixin ContainerMember on ModelElement implements EnclosedElement {
     // TODO(jcollins-g): split Field documentation up between accessors
     // and resolve the pieces with different scopes.  dart-lang/dartdoc#2693.
     // Until then, just pretend we're handling this correctly.
-    yield documentationFrom.first.definingLibrary;
+    yield (documentationFrom.first as ModelElement).definingLibrary;
     // TODO(jcollins-g): Wean users off of depending on canonical library
     // resolution. dart-lang/dartdoc#2696
     if (canonicalLibrary != null) yield canonicalLibrary;