Make many Strings in DocumentationComment non-nullable (#3243)

srawlins · web-flow · commit d14c680c5e66 · 2022-11-11T07:42:38.000-08:00
diff --git a/lib/src/generator/templates.runtime_renderers.dart b/lib/src/generator/templates.runtime_renderers.dart
@@ -3824,10 +3824,10 @@ class _Renderer_Documentable extends RendererBase<Documentable> {
                         nextProperty,
                         [...remainingNames.skip(1)]);
                   },
-                  isNullValue: (CT_ c) => c.oneLineDoc == null,
+                  isNullValue: (CT_ c) => false,
                   renderValue: (CT_ c, RendererBase<CT_> r,
                       List<MustachioNode> ast, StringSink sink) {
-                    _render_String(c.oneLineDoc!, ast, r.template, sink,
+                    _render_String(c.oneLineDoc, ast, r.template, sink,
                         parent: r);
                   },
                 ),
@@ -3942,13 +3942,25 @@ class _Renderer_DocumentationComment
                         nextProperty,
                         [...remainingNames.skip(1)]);
                   },
-                  isNullValue: (CT_ c) => c.documentationLocal == null,
+                  isNullValue: (CT_ c) => false,
                   renderValue: (CT_ c, RendererBase<CT_> r,
                       List<MustachioNode> ast, StringSink sink) {
-                    _render_String(c.documentationLocal!, ast, r.template, sink,
+                    _render_String(c.documentationLocal, ast, r.template, sink,
                         parent: r);
                   },
                 ),
+                'element': Property(
+                  getValue: (CT_ c) => c.element,
+                  renderVariable: (CT_ c, Property<CT_> self,
+                          List<String> remainingNames) =>
+                      self.renderSimpleVariable(c, remainingNames, 'Element'),
+                  isNullValue: (CT_ c) => false,
+                  renderValue: (CT_ c, RendererBase<CT_> r,
+                      List<MustachioNode> ast, StringSink sink) {
+                    renderSimple(c.element, ast, r.template, sink,
+                        parent: r, getters: _invisibleGetters['Element']!);
+                  },
+                ),
                 'elementDocumentation': Property(
                   getValue: (CT_ c) => c.elementDocumentation,
                   renderVariable: (CT_ c, Property<CT_> self,
@@ -9776,29 +9788,6 @@ class _Renderer_ModelElement extends RendererBase<ModelElement> {
                         parent: r);
                   },
                 ),
-                'documentationComment': Property(
-                  getValue: (CT_ c) => c.documentationComment,
-                  renderVariable:
-                      (CT_ c, Property<CT_> self, List<String> remainingNames) {
-                    if (remainingNames.isEmpty) {
-                      return self.getValue(c).toString();
-                    }
-                    var name = remainingNames.first;
-                    var nextProperty =
-                        _Renderer_String.propertyMap().getValue(name);
-                    return nextProperty.renderVariable(
-                        self.getValue(c) as String,
-                        nextProperty,
-                        [...remainingNames.skip(1)]);
-                  },
-                  isNullValue: (CT_ c) => false,
-                  renderValue: (CT_ c, RendererBase<CT_> r,
-                      List<MustachioNode> ast, StringSink sink) {
-                    _render_String(
-                        c.documentationComment, ast, r.template, sink,
-                        parent: r);
-                  },
-                ),
                 'element': Property(
                   getValue: (CT_ c) => c.element,
                   renderVariable: (CT_ c, Property<CT_> self,
@@ -10014,13 +10003,6 @@ class _Renderer_ModelElement extends RendererBase<ModelElement> {
                       self.renderSimpleVariable(c, remainingNames, 'bool'),
                   getBool: (CT_ c) => c.hasDocumentation == true,
                 ),
-                'hasDocumentationComment': Property(
-                  getValue: (CT_ c) => c.hasDocumentationComment,
-                  renderVariable: (CT_ c, Property<CT_> self,
-                          List<String> remainingNames) =>
-                      self.renderSimpleVariable(c, remainingNames, 'bool'),
-                  getBool: (CT_ c) => c.hasDocumentationComment == true,
-                ),
                 'hasFeatures': Property(
                   getValue: (CT_ c) => c.hasFeatures,
                   renderVariable: (CT_ c, Property<CT_> self,
@@ -15798,6 +15780,7 @@ const _invisibleGetters = {
     'documentationComment',
     'documentationFrom',
     'documentationLocal',
+    'element',
     'elementDocumentation',
     'fullyQualifiedNameWithoutLibrary',
     'hasDocumentationComment',
diff --git a/lib/src/model/documentable.dart b/lib/src/model/documentable.dart
@@ -17,7 +17,7 @@ abstract class Documentable extends Nameable {
 
   bool get hasDocumentation;
 
-  String? get oneLineDoc;
+  String get oneLineDoc;
 
   PackageGraph get packageGraph;
 
diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart
@@ -1,3 +1,4 @@
+import 'package:analyzer/dart/element/element.dart';
 import 'package:args/args.dart';
 import 'package:crypto/crypto.dart' as crypto;
 import 'package:dartdoc/src/model/documentable.dart';
@@ -37,6 +38,9 @@ final _htmlInjectRegExp = RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
 /// entrypoints.
 mixin DocumentationComment
     on Documentable, Warnable, Locatable, SourceCodeMixin {
+  @override
+  Element get element;
+
   List<DocumentationComment>? _documentationFrom;
 
   /// The [ModelElement](s) from which we will get documentation.
@@ -56,7 +60,7 @@ mixin DocumentationComment
         if (!hasDocumentationComment && self.overriddenElement != null) {
           return self.overriddenElement!.documentationFrom;
         } else if (self.isInherited) {
-          return modelBuilder.fromElement(element!).documentationFrom;
+          return modelBuilder.fromElement(element).documentationFrom;
         } else {
           return [this];
         }
@@ -71,15 +75,15 @@ mixin DocumentationComment
 
   /// The rawest form of the documentation comment, including comment delimiters
   /// like `///`, `//`, `/*`, `*/`.
-  String get documentationComment;
+  String get documentationComment => element.documentationComment ?? '';
 
   /// True if [this] has a synthetic/inherited or local documentation
   /// comment.  False otherwise.
-  bool get hasDocumentationComment;
+  bool get hasDocumentationComment => element.documentationComment != null;
 
   /// Returns true if the raw documentation comment has a 'nodoc' indication.
   late final bool hasNodoc = () {
-    if (packageGraph.configSetsNodocFor(element!.source!.fullName)) {
+    if (packageGraph.configSetsNodocFor(element.source!.fullName)) {
       return true;
     }
     if (!hasDocumentationComment) {
@@ -331,7 +335,7 @@ mixin DocumentationComment
           replacement = replacement.replaceFirst('```', '```$lang');
         }
       } else {
-        var filePath = element!.source!.fullName.substring(dirPath.length + 1);
+        var filePath = element.source!.fullName.substring(dirPath.length + 1);
 
         // TODO(srawlins): If a file exists at the location without the
         // appended 'md' extension, note this.
@@ -753,20 +757,28 @@ mixin DocumentationComment
     }
   }
 
-  /// Returns the documentation for this literal element unless
-  /// [config.dropTextFrom] indicates it should not be returned.  Macro
-  /// definitions are stripped, but macros themselves are not injected.  This
-  /// is a two stage process to avoid ordering problems.
-  String? _documentationLocal;
+  bool _documentationLocalIsSet = false;
 
-  String? get documentationLocal =>
-      _documentationLocal ??= _buildDocumentationLocal();
+  /// Returns the documentation for this literal element unless
+  /// `config.dropTextFrom` indicates it should not be returned.  Macro
+  /// definitions are stripped, but macros themselves are not injected.  This is
+  /// a two stage process to avoid ordering problems.
+  late final String _documentationLocal;
+
+  String get documentationLocal {
+    if (!_documentationLocalIsSet) {
+      _documentationLocal = _buildDocumentationBaseSync();
+      _documentationLocalIsSet = true;
+    }
+    return _documentationLocal;
+  }
 
   /// Unconditionally precache local documentation.
   ///
   /// Use only in factory for [PackageGraph].
   Future<void> precacheLocalDocs() async {
     _documentationLocal = await _buildDocumentationBase();
+    _documentationLocalIsSet = true;
   }
 
   late final bool _hasNodoc;
@@ -833,35 +845,31 @@ mixin DocumentationComment
 
   String? _rawDocs;
 
-  String? _buildDocumentationLocal() => _buildDocumentationBaseSync();
-
   /// Override this to add more features to the documentation builder in a
   /// subclass.
   String buildDocumentationAddition(String docs) => docs;
 
-  /// Separate from [_buildDocumentationLocal] for overriding.
-  String? _buildDocumentationBaseSync() {
+  String _buildDocumentationBaseSync() {
     assert(_rawDocs == null,
         'reentrant calls to _buildDocumentation* not allowed');
     // Do not use the sync method if we need to evaluate tools or templates.
     assert(!isCanonical || !needsPrecache);
     String rawDocs;
-    if (config.dropTextFrom.contains(element!.library!.name)) {
+    if (config.dropTextFrom.contains(element.library!.name)) {
       rawDocs = '';
     } else {
       rawDocs = _processCommentWithoutTools(documentationComment);
     }
     return _rawDocs = buildDocumentationAddition(rawDocs);
   }
 
-  /// Separate from [_buildDocumentationLocal] for overriding.  Can only be
-  /// used as part of [PackageGraph.setUpPackageGraph].
-  Future<String?> _buildDocumentationBase() async {
+  /// Can only be used as part of `PackageGraph.setUpPackageGraph`.
+  Future<String> _buildDocumentationBase() async {
     assert(_rawDocs == null,
         'reentrant calls to _buildDocumentation* not allowed');
     String rawDocs;
     // Do not use the sync method if we need to evaluate tools or templates.
-    if (config.dropTextFrom.contains(element!.library!.name)) {
+    if (config.dropTextFrom.contains(element.library!.name)) {
       rawDocs = '';
     } else {
       rawDocs = await processComment(documentationComment);
diff --git a/lib/src/model/getter_setter_combo.dart b/lib/src/model/getter_setter_combo.dart
@@ -190,7 +190,7 @@ mixin GetterSetterCombo on ModelElement {
         // We have to check against `dropTextFrom` here since
         // `documentationFrom` doesn't yield the real elements for
         // [GetterSetterCombo]s.
-        if (!config.dropTextFrom.contains(fromGetter.element!.library!.name)) {
+        if (!config.dropTextFrom.contains(fromGetter.element.library!.name)) {
           if (fromGetter.hasDocumentationComment) {
             getterComment = fromGetter.documentationComment;
           }
@@ -206,7 +206,7 @@ mixin GetterSetterCombo on ModelElement {
     if (!setter.isSynthetic && setter.isPublic) {
       assert(setter.documentationFrom.length == 1);
       var fromSetter = setter.documentationFrom.first;
-      if (!config.dropTextFrom.contains(fromSetter.element!.library!.name)) {
+      if (!config.dropTextFrom.contains(fromSetter.element.library!.name)) {
         if (fromSetter.hasDocumentationComment) {
           return getterComment.isEmpty
               ? fromSetter.documentationComment
diff --git a/lib/src/model/model_element.dart b/lib/src/model/model_element.dart
@@ -879,12 +879,6 @@ abstract class ModelElement extends Canonicalization
     );
   }();
 
-  @override
-  String get documentationComment => element.documentationComment ?? '';
-
-  @override
-  bool get hasDocumentationComment => element.documentationComment != null;
-
   @override
   late final String sourceCode =
       _sourceCodeRenderer.renderSourceCode(super.sourceCode);
diff --git a/test/end2end/model_test.dart b/test/end2end/model_test.dart
@@ -3796,7 +3796,7 @@ String? topLevelFunction(int param1, bool param2, Cool coolBeans,
     test('inheritance of docs from SDK works for getter/setter combos', () {
       expect(
           ExtraSpecialListLength
-              .getter!.documentationFrom.first.element!.library!.name,
+              .getter!.documentationFrom.first.element.library!.name,
           equals('dart.core'));
       expect(ExtraSpecialListLength.oneLineDoc == '', isFalse);
     });
