From c867d5f1008e4bfec0f84aa0b8ca0f10c7c00014 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Tue, 28 Sep 2021 16:35:18 -0700 Subject: [PATCH 1/5] Straight move --- lib/src/model/built_documentation.dart | 61 ++++++++++++++++++++++++ lib/src/model/documentation_comment.dart | 61 +++++++++++++++++++++++- lib/src/model/model.dart | 2 +- lib/src/model/model_element.dart | 55 +-------------------- 4 files changed, 123 insertions(+), 56 deletions(-) create mode 100644 lib/src/model/built_documentation.dart diff --git a/lib/src/model/built_documentation.dart b/lib/src/model/built_documentation.dart new file mode 100644 index 0000000000..6e0b402ee1 --- /dev/null +++ b/lib/src/model/built_documentation.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. + +import 'package:dartdoc/src/model/documentation_comment.dart'; +import 'package:dartdoc/src/model/model_element.dart'; +import 'package:dartdoc/src/utils.dart'; +/* +final RegExp _needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); + +class BuiltDocumentation { + + final DocumentationComment modelElement; + + BuiltDocumentation(this.modelElement); + + @deprecated + String buildDocumentationAddition(String docs) => docs ??= ''; + + String _rawDocs; + String _documentationLocal; + /// 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 get documentationLocal => _documentationLocal ??= () { + assert(_rawDocs == null, + 'reentrant calls to _buildDocumentation* not allowed'); + // Do not use the sync method if we need to evaluate tools or templates. + assert(!modelElement.isCanonical || + !_needsPrecacheRegExp.hasMatch(modelElement.documentationComment ?? '')); + if (modelElement.config.dropTextFrom.contains(modelElement.element.library.name)) { + _rawDocs = ''; + } else { + _rawDocs = _processCommentWithoutTools(modelElement.documentationComment ?? ''); + } + _rawDocs = buildDocumentationAddition(_rawDocs); + return _rawDocs; + } (); + + /// Process a [documentationComment], performing various actions based on + /// `{@}`-style directives, except `{@tool}`, returning the processed result. + String _processCommentWithoutTools(String documentationComment) { + var docs = stripComments(documentationComment); + if (!docs.contains('{@')) { + _analyzeCodeBlocks(docs); + return docs; + } + docs = _injectExamples(docs); + docs = _injectYouTube(docs); + docs = _injectAnimations(docs); + + _analyzeCodeBlocks(docs); + + // TODO(srawlins): Processing templates here causes #2281. But leaving them + // unprocessed causes #2272. + docs = _stripHtmlAndAddToIndex(docs); + return docs; + } +} +*/ diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 1422cc8f5b..4582ac618e 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -1,6 +1,8 @@ import 'package:args/args.dart'; import 'package:crypto/crypto.dart' as crypto; -import 'package:dartdoc/src/model/model.dart'; +import 'package:dartdoc/src/model/documentable.dart'; +import 'package:dartdoc/src/model/locatable.dart'; +import 'package:dartdoc/src/model/source_code_mixin.dart'; import 'package:dartdoc/src/render/model_element_renderer.dart'; import 'package:dartdoc/src/utils.dart'; import 'package:dartdoc/src/warnings.dart'; @@ -23,6 +25,8 @@ final _basicToolPattern = RegExp( final _examplePattern = RegExp(r'{@example\s+([^}]+)}'); +final RegExp needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); + /// Features for processing directives in a documentation comment. /// /// [processCommentWithoutTools] and [processComment] are the primary @@ -707,4 +711,59 @@ 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; + + String get documentationLocal => + _documentationLocal ??= _buildDocumentationLocal(); + + /// Unconditionally precache local documentation. + /// + /// Use only in factory for [PackageGraph]. + Future precacheLocalDocs() async { + _documentationLocal = await _buildDocumentationBase(); + } + + 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() { + 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 || + !needsPrecacheRegExp.hasMatch(documentationComment ?? '')); + if (config.dropTextFrom.contains(element.library.name)) { + _rawDocs = ''; + } else { + _rawDocs = processCommentWithoutTools(documentationComment ?? ''); + } + _rawDocs = buildDocumentationAddition(_rawDocs); + return _rawDocs; + } + + /// Separate from _buildDocumentationLocal for overriding. Can only be + /// used as part of [PackageGraph.setUpPackageGraph]. + Future _buildDocumentationBase() async { + assert(_rawDocs == null, + 'reentrant calls to _buildDocumentation* not allowed'); + // Do not use the sync method if we need to evaluate tools or templates. + if (config.dropTextFrom.contains(element.library.name)) { + _rawDocs = ''; + } else { + _rawDocs = await processComment(documentationComment ?? ''); + } + _rawDocs = buildDocumentationAddition(_rawDocs); + return _rawDocs; + } } diff --git a/lib/src/model/model.dart b/lib/src/model/model.dart index a6d40f3d2f..694dc1fbe1 100644 --- a/lib/src/model/model.dart +++ b/lib/src/model/model.dart @@ -28,7 +28,7 @@ export 'library_container.dart'; export 'locatable.dart'; export 'method.dart'; export 'mixin.dart'; -export 'model_element.dart'; +export 'model_element.dart' hide needsPrecacheRegExp; export 'model_function.dart'; export 'model_node.dart'; export 'nameable.dart'; diff --git a/lib/src/model/model_element.dart b/lib/src/model/model_element.dart index 9d834dd151..a905ea32a5 100644 --- a/lib/src/model/model_element.dart +++ b/lib/src/model/model_element.dart @@ -36,6 +36,7 @@ import 'package:path/path.dart' as path show Context; /// This doc may need to be processed in case it has a template or html /// fragment. +@Deprecated('Use version in documentation_comment.dart.') final RegExp needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); final _htmlInjectRegExp = RegExp(r'([a-f0-9]+)'); @@ -118,7 +119,6 @@ abstract class ModelElement extends Canonicalization final Member /*?*/ _originalMember; final Library /*?*/ _library; - String _rawDocs; Documentation __documentation; UnmodifiableListView _parameters; String _linkedName; @@ -546,52 +546,6 @@ abstract class ModelElement extends Canonicalization } } - 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() { - 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 || - !needsPrecacheRegExp.hasMatch(documentationComment ?? '')); - if (config.dropTextFrom.contains(element.library.name)) { - _rawDocs = ''; - } else { - _rawDocs = processCommentWithoutTools(documentationComment ?? ''); - } - _rawDocs = buildDocumentationAddition(_rawDocs); - return _rawDocs; - } - - /// Separate from _buildDocumentationLocal for overriding. Can only be - /// used as part of [PackageGraph.setUpPackageGraph]. - Future _buildDocumentationBase() async { - assert(_rawDocs == null, - 'reentrant calls to _buildDocumentation* not allowed'); - // Do not use the sync method if we need to evaluate tools or templates. - if (config.dropTextFrom.contains(element.library.name)) { - _rawDocs = ''; - } else { - _rawDocs = await processComment(documentationComment ?? ''); - } - _rawDocs = buildDocumentationAddition(_rawDocs); - return _rawDocs; - } - - /// 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; - - String get documentationLocal => - _documentationLocal ??= _buildDocumentationLocal(); - /// Returns the docs, stripped of their leading comments syntax. @override String get documentation { @@ -1022,13 +976,6 @@ abstract class ModelElement extends Canonicalization @override String computeDocumentationComment() => element.documentationComment; - /// Unconditionally precache local documentation. - /// - /// Use only in factory for [PackageGraph]. - Future precacheLocalDocs() async { - _documentationLocal = await _buildDocumentationBase(); - } - Documentation get _documentation { if (__documentation != null) return __documentation; __documentation = Documentation.forElement(this); From 08b4b6cf3b71f4661728eb940ee3f7d246a8353c Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Tue, 28 Sep 2021 17:09:32 -0700 Subject: [PATCH 2/5] Partial --- lib/src/model/documentation_comment.dart | 103 +++++++++++++++++-- lib/src/model/model.dart | 2 +- lib/src/model/model_element.dart | 125 +++-------------------- lib/src/model/package_graph.dart | 3 +- 4 files changed, 112 insertions(+), 121 deletions(-) diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 4582ac618e..6806106a86 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -25,11 +25,15 @@ final _basicToolPattern = RegExp( final _examplePattern = RegExp(r'{@example\s+([^}]+)}'); -final RegExp needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); +final _macroRegExp = RegExp(r'{@macro\s+([^}]+)}'); + +final _htmlInjectRegExp = RegExp(r'([a-f0-9]+)'); + +final RegExp _needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); /// Features for processing directives in a documentation comment. /// -/// [processCommentWithoutTools] and [processComment] are the primary +/// [_processCommentWithoutTools] and [processComment] are the primary /// entrypoints. mixin DocumentationComment on Documentable, Warnable, Locatable, SourceCodeMixin { @@ -63,7 +67,7 @@ mixin DocumentationComment /// Process a [documentationComment], performing various actions based on /// `{@}`-style directives, except `{@tool}`, returning the processed result. - String processCommentWithoutTools(String documentationComment) { + String _processCommentWithoutTools(String documentationComment) { var docs = stripComments(documentationComment); if (!docs.contains('{@')) { _analyzeCodeBlocks(docs); @@ -83,6 +87,7 @@ mixin DocumentationComment /// Process [documentationComment], performing various actions based on /// `{@}`-style directives, returning the processed result. + @visibleForTesting Future processComment(String documentationComment) async { var docs = stripComments(documentationComment); // Must evaluate tools first, in case they insert any other directives. @@ -728,6 +733,10 @@ mixin DocumentationComment _documentationLocal = await _buildDocumentationBase(); } + bool _needsPrecache; + bool get needsPrecache => _needsPrecache ??= + _needsPrecacheRegExp.hasMatch(documentationComment ?? ''); + String _rawDocs; String _buildDocumentationLocal() => _buildDocumentationBaseSync(); @@ -741,12 +750,11 @@ mixin DocumentationComment 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 || - !needsPrecacheRegExp.hasMatch(documentationComment ?? '')); + assert(!isCanonical || !needsPrecache); if (config.dropTextFrom.contains(element.library.name)) { _rawDocs = ''; } else { - _rawDocs = processCommentWithoutTools(documentationComment ?? ''); + _rawDocs = _processCommentWithoutTools(documentationComment ?? ''); } _rawDocs = buildDocumentationAddition(_rawDocs); return _rawDocs; @@ -766,4 +774,87 @@ mixin DocumentationComment _rawDocs = buildDocumentationAddition(_rawDocs); return _rawDocs; } + + /// Replace <[digest]> in API comments with + /// the contents of the HTML fragment earlier defined by the + /// {@inject-html} directive. The [digest] is a SHA1 of the contents + /// of the HTML fragment, automatically generated upon parsing the + /// {@inject-html} directive. + /// + /// This markup is generated and inserted by [_stripHtmlAndAddToIndex] when it + /// removes the HTML fragment in preparation for markdown processing. It isn't + /// meant to be used at a user level. + /// + /// Example: + /// + /// You place the fragment in a dartdoc comment: + /// + /// Some comments + /// {@inject-html} + /// <p>[HTML contents!]</p> + /// {@endtemplate} + /// More comments + /// + /// and [_stripHtmlAndAddToIndex] will replace your HTML fragment with this: + /// + /// Some comments + /// <dartdoc-html>4cc02f877240bf69855b4c7291aba8a16e5acce0</dartdoc-html> + /// More comments + /// + /// Which will render in the final HTML output as: + /// + /// Some comments + /// <p>[HTML contents!]</p> + /// More comments + /// + /// And the HTML fragment will not have been processed or changed by Markdown, + /// but just injected verbatim. + String injectHtmlFragments(String rawDocs) { + if (!config.injectHtml) return rawDocs; + + return rawDocs.replaceAllMapped(_htmlInjectRegExp, (match) { + var fragment = packageGraph.getHtmlFragment(match[1]); + if (fragment == null) { + warn(PackageWarning.unknownHtmlFragment, message: match[1]); + } + return fragment; + }); + } + + /// Replace {@macro ...} in API comments with the contents of the macro + /// + /// Syntax: + /// + /// {@macro NAME} + /// + /// Example: + /// + /// You define the template in any comment for a documentable entity like: + /// + /// {@template foo} + /// Foo contents! + /// {@endtemplate} + /// + /// and them somewhere use it like this: + /// + /// Some comments + /// {@macro foo} + /// More comments + /// + /// Which will render + /// + /// Some comments + /// Foo contents! + /// More comments + /// + String injectMacros(String rawDocs) { + return rawDocs.replaceAllMapped(_macroRegExp, (match) { + var macro = packageGraph.getMacro(match[1]); + if (macro == null) { + warn(PackageWarning.unknownMacro, message: match[1]); + } + macro = processCommentDirectives(macro ?? ''); + return macro; + }); + } } diff --git a/lib/src/model/model.dart b/lib/src/model/model.dart index 694dc1fbe1..a6d40f3d2f 100644 --- a/lib/src/model/model.dart +++ b/lib/src/model/model.dart @@ -28,7 +28,7 @@ export 'library_container.dart'; export 'locatable.dart'; export 'method.dart'; export 'mixin.dart'; -export 'model_element.dart' hide needsPrecacheRegExp; +export 'model_element.dart'; export 'model_function.dart'; export 'model_node.dart'; export 'nameable.dart'; diff --git a/lib/src/model/model_element.dart b/lib/src/model/model_element.dart index a905ea32a5..6eaa00a4b6 100644 --- a/lib/src/model/model_element.dart +++ b/lib/src/model/model_element.dart @@ -34,21 +34,6 @@ import 'package:dartdoc/src/warnings.dart'; import 'package:meta/meta.dart'; import 'package:path/path.dart' as path show Context; -/// This doc may need to be processed in case it has a template or html -/// fragment. -@Deprecated('Use version in documentation_comment.dart.') -final RegExp needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); - -final _htmlInjectRegExp = RegExp(r'([a-f0-9]+)'); -@Deprecated('Public variable intended to be private; will be removed as early ' - 'as Dartdoc 1.0.0') -RegExp get htmlInjectRegExp => _htmlInjectRegExp; - -final _macroRegExp = RegExp(r'{@macro\s+([^}]+)}'); -@Deprecated('Public variable intended to be private; will be removed as early ' - 'as Dartdoc 1.0.0') -RegExp get macroRegExp => _macroRegExp; - // TODO(jcollins-g): Implement resolution per ECMA-408 4th edition, page 39 #22. /// Resolves this very rare case incorrectly by picking the closest element in /// the inheritance and interface chains from the analyzer. @@ -546,13 +531,6 @@ abstract class ModelElement extends Canonicalization } } - /// Returns the docs, stripped of their leading comments syntax. - @override - String get documentation { - return _injectMacros( - documentationFrom.map((e) => e.documentationLocal).join('

')); - } - Library get definingLibrary { var library = packageGraph.findButDoNotCreateLibraryFor(element); if (library == null) { @@ -689,13 +667,19 @@ abstract class ModelElement extends Canonicalization return i.enclosingElement == i.canonicalEnclosingContainer; } - String _htmlDocumentation; + /// Returns the docs, stripped of their leading comments syntax. + @override + String get documentation { + return injectMacros( + documentationFrom.map((e) => e.documentationLocal).join('

')); + } + String _documentationAsHtml; @override String get documentationAsHtml { - if (_htmlDocumentation != null) return _htmlDocumentation; - _htmlDocumentation = _injectHtmlFragments(_documentation.asHtml); - return _htmlDocumentation; + if (_documentationAsHtml != null) return _documentationAsHtml; + _documentationAsHtml = injectHtmlFragments(_elementDocumentation.asHtml); + return _documentationAsHtml; } @override @@ -778,7 +762,7 @@ abstract class ModelElement extends Canonicalization @override bool get hasExtendedDocumentation => - href != null && _documentation.hasExtendedDocs; + href != null && _elementDocumentation.hasExtendedDocs; bool get hasParameters => parameters.isNotEmpty; @@ -883,7 +867,7 @@ abstract class ModelElement extends Canonicalization String get name => _name ??= element.name; @override - String get oneLineDoc => _documentation.asOneLiner; + String get oneLineDoc => _elementDocumentation.asOneLiner; Member get originalMember => _originalMember; @@ -976,7 +960,7 @@ abstract class ModelElement extends Canonicalization @override String computeDocumentationComment() => element.documentationComment; - Documentation get _documentation { + Documentation get _elementDocumentation { if (__documentation != null) return __documentation; __documentation = Documentation.forElement(this); return __documentation; @@ -1034,87 +1018,4 @@ abstract class ModelElement extends Canonicalization return modelElementRenderer.renderLinkedName(this); } - - /// Replace <[digest]> in API comments with - /// the contents of the HTML fragment earlier defined by the - /// {@inject-html} directive. The [digest] is a SHA1 of the contents - /// of the HTML fragment, automatically generated upon parsing the - /// {@inject-html} directive. - /// - /// This markup is generated and inserted by [_stripHtmlAndAddToIndex] when it - /// removes the HTML fragment in preparation for markdown processing. It isn't - /// meant to be used at a user level. - /// - /// Example: - /// - /// You place the fragment in a dartdoc comment: - /// - /// Some comments - /// {@inject-html} - /// <p>[HTML contents!]</p> - /// {@endtemplate} - /// More comments - /// - /// and [_stripHtmlAndAddToIndex] will replace your HTML fragment with this: - /// - /// Some comments - /// <dartdoc-html>4cc02f877240bf69855b4c7291aba8a16e5acce0</dartdoc-html> - /// More comments - /// - /// Which will render in the final HTML output as: - /// - /// Some comments - /// <p>[HTML contents!]</p> - /// More comments - /// - /// And the HTML fragment will not have been processed or changed by Markdown, - /// but just injected verbatim. - String _injectHtmlFragments(String rawDocs) { - if (!config.injectHtml) return rawDocs; - - return rawDocs.replaceAllMapped(_htmlInjectRegExp, (match) { - var fragment = packageGraph.getHtmlFragment(match[1]); - if (fragment == null) { - warn(PackageWarning.unknownHtmlFragment, message: match[1]); - } - return fragment; - }); - } - - /// Replace {@macro ...} in API comments with the contents of the macro - /// - /// Syntax: - /// - /// {@macro NAME} - /// - /// Example: - /// - /// You define the template in any comment for a documentable entity like: - /// - /// {@template foo} - /// Foo contents! - /// {@endtemplate} - /// - /// and them somewhere use it like this: - /// - /// Some comments - /// {@macro foo} - /// More comments - /// - /// Which will render - /// - /// Some comments - /// Foo contents! - /// More comments - /// - String _injectMacros(String rawDocs) { - return rawDocs.replaceAllMapped(_macroRegExp, (match) { - var macro = packageGraph.getMacro(match[1]); - if (macro == null) { - warn(PackageWarning.unknownMacro, message: match[1]); - } - macro = processCommentDirectives(macro ?? ''); - return macro; - }); - } } diff --git a/lib/src/model/package_graph.dart b/lib/src/model/package_graph.dart index 07b26ef911..26210a2d7d 100644 --- a/lib/src/model/package_graph.dart +++ b/lib/src/model/package_graph.dart @@ -135,8 +135,7 @@ class PackageGraph with CommentReferable, Nameable { Iterable> precacheOneElement(ModelElement m) sync* { for (var d in m.documentationFrom.where((d) => d.documentationComment != null)) { - if (needsPrecacheRegExp.hasMatch(d.documentationComment) && - !precachedElements.contains(d)) { + if (d.needsPrecache && !precachedElements.contains(d)) { precachedElements.add(d); yield d.precacheLocalDocs(); logProgress(d.name); From 0a975cddbf2e0bd260c8a806181cd7e43d7f7596 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Wed, 29 Sep 2021 12:55:32 -0700 Subject: [PATCH 3/5] delete experiment --- lib/src/model/built_documentation.dart | 61 -------------------------- 1 file changed, 61 deletions(-) delete mode 100644 lib/src/model/built_documentation.dart diff --git a/lib/src/model/built_documentation.dart b/lib/src/model/built_documentation.dart deleted file mode 100644 index 6e0b402ee1..0000000000 --- a/lib/src/model/built_documentation.dart +++ /dev/null @@ -1,61 +0,0 @@ -// 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. - -import 'package:dartdoc/src/model/documentation_comment.dart'; -import 'package:dartdoc/src/model/model_element.dart'; -import 'package:dartdoc/src/utils.dart'; -/* -final RegExp _needsPrecacheRegExp = RegExp(r'{@(template|tool|inject-html)'); - -class BuiltDocumentation { - - final DocumentationComment modelElement; - - BuiltDocumentation(this.modelElement); - - @deprecated - String buildDocumentationAddition(String docs) => docs ??= ''; - - String _rawDocs; - String _documentationLocal; - /// 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 get documentationLocal => _documentationLocal ??= () { - assert(_rawDocs == null, - 'reentrant calls to _buildDocumentation* not allowed'); - // Do not use the sync method if we need to evaluate tools or templates. - assert(!modelElement.isCanonical || - !_needsPrecacheRegExp.hasMatch(modelElement.documentationComment ?? '')); - if (modelElement.config.dropTextFrom.contains(modelElement.element.library.name)) { - _rawDocs = ''; - } else { - _rawDocs = _processCommentWithoutTools(modelElement.documentationComment ?? ''); - } - _rawDocs = buildDocumentationAddition(_rawDocs); - return _rawDocs; - } (); - - /// Process a [documentationComment], performing various actions based on - /// `{@}`-style directives, except `{@tool}`, returning the processed result. - String _processCommentWithoutTools(String documentationComment) { - var docs = stripComments(documentationComment); - if (!docs.contains('{@')) { - _analyzeCodeBlocks(docs); - return docs; - } - docs = _injectExamples(docs); - docs = _injectYouTube(docs); - docs = _injectAnimations(docs); - - _analyzeCodeBlocks(docs); - - // TODO(srawlins): Processing templates here causes #2281. But leaving them - // unprocessed causes #2272. - docs = _stripHtmlAndAddToIndex(docs); - return docs; - } -} -*/ From 61696c7b1ef9abb7fd6c411c02e23a68e3c120f8 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Wed, 29 Sep 2021 12:57:37 -0700 Subject: [PATCH 4/5] rebuild --- .../templates.runtime_renderers.dart | 48 +++++++++++-------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/lib/src/generator/templates.runtime_renderers.dart b/lib/src/generator/templates.runtime_renderers.dart index f7fa4d9ad4..5abfcd2d64 100644 --- a/lib/src/generator/templates.runtime_renderers.dart +++ b/lib/src/generator/templates.runtime_renderers.dart @@ -3928,6 +3928,26 @@ class _Renderer_DocumentationComment parent: r); }, ), + 'documentationLocal': Property( + getValue: (CT_ c) => c.documentationLocal, + renderVariable: + (CT_ c, Property self, List 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), + nextProperty, [...remainingNames.skip(1)]); + }, + isNullValue: (CT_ c) => c.documentationLocal == null, + renderValue: (CT_ c, RendererBase r, + List ast, StringSink sink) { + _render_String(c.documentationLocal, ast, r.template, sink, + parent: r); + }, + ), 'fullyQualifiedNameWithoutLibrary': Property( getValue: (CT_ c) => c.fullyQualifiedNameWithoutLibrary, renderVariable: @@ -3971,6 +3991,13 @@ class _Renderer_DocumentationComment getters: _invisibleGetters['ModelElementRenderer']); }, ), + 'needsPrecache': Property( + getValue: (CT_ c) => c.needsPrecache, + renderVariable: (CT_ c, Property self, + List remainingNames) => + self.renderSimpleVariable(c, remainingNames, 'bool'), + getBool: (CT_ c) => c.needsPrecache == true, + ), 'pathContext': Property( getValue: (CT_ c) => c.pathContext, renderVariable: (CT_ c, Property self, @@ -4229,6 +4256,7 @@ class _Renderer_Enum extends RendererBase { CT_, () => { ..._Renderer_InheritingContainer.propertyMap(), + ..._Renderer_TypeImplementing.propertyMap(), 'inheritanceChain': Property( getValue: (CT_ c) => c.inheritanceChain, renderVariable: (CT_ c, Property self, @@ -9481,26 +9509,6 @@ class _Renderer_ModelElement extends RendererBase { parent: r)); }, ), - 'documentationLocal': Property( - getValue: (CT_ c) => c.documentationLocal, - renderVariable: - (CT_ c, Property self, List 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), - nextProperty, [...remainingNames.skip(1)]); - }, - isNullValue: (CT_ c) => c.documentationLocal == null, - renderValue: (CT_ c, RendererBase r, - List ast, StringSink sink) { - _render_String(c.documentationLocal, ast, r.template, sink, - parent: r); - }, - ), 'element': Property( getValue: (CT_ c) => c.element, renderVariable: (CT_ c, Property self, From 41e1fde1e9a24e98fc40a6202139b3dae434c982 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Thu, 30 Sep 2021 09:55:19 -0700 Subject: [PATCH 5/5] remove ??= from a cut and paste --- lib/src/model/documentation_comment.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index 6806106a86..405804dc3f 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -743,7 +743,7 @@ mixin DocumentationComment /// Override this to add more features to the documentation builder in a /// subclass. - String buildDocumentationAddition(String docs) => docs ??= ''; + String buildDocumentationAddition(String docs) => docs ?? ''; /// Separate from _buildDocumentationLocal for overriding. String _buildDocumentationBaseSync() {