diff --git a/CHANGELOG.md b/CHANGELOG.md index e47033a8da..19d700216e 100644 --- a/CHANGELOG.md +++ b/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). diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml index 242689dbfc..5e293ce510 100644 --- a/dartdoc_options.yaml +++ b/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%' diff --git a/lib/src/comment_references/parser.dart b/lib/src/comment_references/parser.dart index 37d507bd0e..5624c169f7 100644 --- a/lib/src/comment_references/parser.dart +++ b/lib/src/comment_references/parser.dart @@ -96,7 +96,7 @@ class CommentReferenceParser { /// ```text /// ::= ?? /// - /// ::= ( '.')? ( '.')? ('.' )* + /// ::= ( '.')? ( '.')? ('.' )* /// ``` List _parseRawCommentReference() { var children = []; @@ -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"]'; +} diff --git a/lib/src/generator/generator_frontend.dart b/lib/src/generator/generator_frontend.dart index 30e31ab184..4754c549c3 100644 --- a/lib/src/generator/generator_frontend.dart +++ b/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); diff --git a/lib/src/generator/template_data.dart b/lib/src/generator/template_data.dart index e505359425..69ac0022a0 100644 --- a/lib/src/generator/template_data.dart +++ b/lib/src/generator/template_data.dart @@ -175,34 +175,51 @@ class LibraryTemplateData extends TemplateData } /// Template data for Dart 2.1-style mixin declarations. -class MixinTemplateData extends ClassTemplateData { - final Mixin mixin; - +class MixinTemplateData extends InheritingContainerTemplateData { 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 { + 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 extends TemplateData +abstract class InheritingContainerTemplateData + extends TemplateData implements TemplateDataWithLibrary, TemplateDataWithContainer { - 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 'for the Dart programming language.'; } -class EnumTemplateData extends ClassTemplateData { +class EnumTemplateData extends InheritingContainerTemplateData { EnumTemplateData( TemplateOptions htmlOptions, PackageGraph packageGraph, diff --git a/lib/src/generator/templates.aot_renderers_for_html.dart b/lib/src/generator/templates.aot_renderers_for_html.dart index 8eb4ee4fcd..ee0b36ddab 100644 --- a/lib/src/generator/templates.aot_renderers_for_html.dart +++ b/lib/src/generator/templates.aot_renderers_for_html.dart @@ -9,25 +9,26 @@ // ignore_for_file: unused_local_variable // @dart=2.9 -import 'dart:convert' as _i18; +import 'dart:convert' as _i19; import 'package:dartdoc/src/generator/template_data.dart' as _i1; -import 'package:dartdoc/src/model/accessor.dart' as _i16; +import 'package:dartdoc/src/model/accessor.dart' as _i17; import 'package:dartdoc/src/model/category.dart' as _i2; -import 'package:dartdoc/src/model/class.dart' as _i4; +import 'package:dartdoc/src/model/class.dart' as _i8; import 'package:dartdoc/src/model/constructor.dart' as _i11; -import 'package:dartdoc/src/model/documentable.dart' as _i17; +import 'package:dartdoc/src/model/container.dart' as _i4; +import 'package:dartdoc/src/model/documentable.dart' as _i18; import 'package:dartdoc/src/model/enum.dart' as _i12; import 'package:dartdoc/src/model/extension.dart' as _i13; import 'package:dartdoc/src/model/field.dart' as _i9; import 'package:dartdoc/src/model/library.dart' as _i3; import 'package:dartdoc/src/model/library_container.dart' as _i15; import 'package:dartdoc/src/model/method.dart' as _i10; -import 'package:dartdoc/src/model/mixin.dart' as _i5; -import 'package:dartdoc/src/model/model_function.dart' as _i7; +import 'package:dartdoc/src/model/mixin.dart' as _i16; +import 'package:dartdoc/src/model/model_function.dart' as _i6; import 'package:dartdoc/src/model/package.dart' as _i14; -import 'package:dartdoc/src/model/top_level_variable.dart' as _i6; -import 'package:dartdoc/src/model/typedef.dart' as _i8; +import 'package:dartdoc/src/model/top_level_variable.dart' as _i5; +import 'package:dartdoc/src/model/typedef.dart' as _i7; String renderCategory(_i1.CategoryTemplateData context0) { final buffer = StringBuffer(); @@ -80,8 +81,8 @@ String renderCategory(_i1.CategoryTemplateData context0) { if (context4 != null) { for (var context5 in context4) { buffer.write('\n '); - buffer.write( - _renderCategory_partial_class_3(context5, context1, context0)); + buffer.write(_renderCategory_partial_container_3( + context5, context1, context0)); } } buffer.writeln(); @@ -101,8 +102,8 @@ String renderCategory(_i1.CategoryTemplateData context0) { if (context6 != null) { for (var context7 in context6) { buffer.write('\n '); - buffer.write( - _renderCategory_partial_mixin_4(context7, context1, context0)); + buffer.write(_renderCategory_partial_container_3( + context7, context1, context0)); } } buffer.writeln(); @@ -123,7 +124,7 @@ String renderCategory(_i1.CategoryTemplateData context0) { for (var context9 in context8) { buffer.write('\n '); buffer.write( - _renderCategory_partial_constant_5(context9, context1, context0)); + _renderCategory_partial_constant_4(context9, context1, context0)); } } buffer.writeln(); @@ -143,7 +144,7 @@ String renderCategory(_i1.CategoryTemplateData context0) { if (context10 != null) { for (var context11 in context10) { buffer.write('\n '); - buffer.write(_renderCategory_partial_property_6( + buffer.write(_renderCategory_partial_property_5( context11, context1, context0)); } } @@ -164,7 +165,7 @@ String renderCategory(_i1.CategoryTemplateData context0) { if (context12 != null) { for (var context13 in context12) { buffer.write('\n '); - buffer.write(_renderCategory_partial_callable_7( + buffer.write(_renderCategory_partial_callable_6( context13, context1, context0)); } } @@ -185,8 +186,8 @@ String renderCategory(_i1.CategoryTemplateData context0) { if (context14 != null) { for (var context15 in context14) { buffer.write('\n '); - buffer.write( - _renderCategory_partial_class_3(context15, context1, context0)); + buffer.write(_renderCategory_partial_container_3( + context15, context1, context0)); } } buffer.writeln(); @@ -207,7 +208,7 @@ String renderCategory(_i1.CategoryTemplateData context0) { for (var context17 in context16) { buffer.write('\n '); buffer.write( - _renderCategory_partial_typedef_8(context17, context1, context0)); + _renderCategory_partial_typedef_7(context17, context1, context0)); } } buffer.writeln(); @@ -227,8 +228,8 @@ String renderCategory(_i1.CategoryTemplateData context0) { if (context18 != null) { for (var context19 in context18) { buffer.write('\n '); - buffer.write( - _renderCategory_partial_class_3(context19, context1, context0)); + buffer.write(_renderCategory_partial_container_3( + context19, context1, context0)); } } buffer.writeln(); @@ -244,7 +245,7 @@ String renderCategory(_i1.CategoryTemplateData context0) { @@ -265,13 +266,13 @@ String renderCategory(_i1.CategoryTemplateData context0) { buffer.writeEscaped(context0.self.kind.toString()); buffer.write(''' '''); - buffer.write(_renderCategory_partial_sidebar_for_category_11(context0)); + buffer.write(_renderCategory_partial_sidebar_for_category_10(context0)); buffer.writeln(); buffer.write(''' '''); - buffer.write(_renderCategory_partial_footer_12(context0)); + buffer.write(_renderCategory_partial_footer_11(context0)); buffer.writeln(); return buffer.toString(); @@ -495,7 +496,7 @@ String __renderCategory_partial_library_2_partial_categorization_0( return buffer.toString(); } -String _renderCategory_partial_class_3(_i4.Class context2, +String _renderCategory_partial_container_3(_i4.Container context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
- '''); - buffer.write(context2.linkedName.toString()); - buffer.write(context2.linkedGenericParameters.toString()); - buffer.write(''' '''); - buffer.write(__renderCategory_partial_mixin_4_partial_categorization_0( - context2, context1, context0)); - buffer.writeln(); - buffer.write(''' -
-
- '''); - buffer.write(context2.oneLineDoc.toString()); - buffer.write(' '); - buffer.write(context2.extendedDocLink.toString()); - buffer.writeln(); - buffer.write(''' -
-'''); - - return buffer.toString(); -} - -String __renderCategory_partial_mixin_4_partial_categorization_0( - _i5.Mixin context2, - _i2.Category context1, - _i1.CategoryTemplateData context0) { - final buffer = StringBuffer(); - if (context2.hasCategoryNames == true) { - var context3 = context2.displayedCategories; - if (context3 != null) { - for (var context4 in context3) { - buffer.write('\n '); - buffer.write(context4.categoryLabel.toString()); - } - } - } - buffer.writeln(); - - return buffer.toString(); -} - -String _renderCategory_partial_constant_5(_i6.TopLevelVariable context2, +String _renderCategory_partial_constant_4(_i5.TopLevelVariable context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
'''); - buffer.write(__renderCategory_partial_property_6_partial_categorization_0( + buffer.write(__renderCategory_partial_property_5_partial_categorization_0( context2, context1, context0)); buffer.writeln(); buffer.write(''' @@ -707,7 +657,7 @@ String _renderCategory_partial_property_6(_i6.TopLevelVariable context2, buffer.write(' '); buffer.write(context2.extendedDocLink.toString()); buffer.write('\n '); - buffer.write(__renderCategory_partial_property_6_partial_features_1( + buffer.write(__renderCategory_partial_property_5_partial_features_1( context2, context1, context0)); buffer.writeln(); buffer.write(''' @@ -717,8 +667,8 @@ String _renderCategory_partial_property_6(_i6.TopLevelVariable context2, return buffer.toString(); } -String __renderCategory_partial_property_6_partial_categorization_0( - _i6.TopLevelVariable context2, +String __renderCategory_partial_property_5_partial_categorization_0( + _i5.TopLevelVariable context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); @@ -736,8 +686,8 @@ String __renderCategory_partial_property_6_partial_categorization_0( return buffer.toString(); } -String __renderCategory_partial_property_6_partial_features_1( - _i6.TopLevelVariable context2, +String __renderCategory_partial_property_5_partial_features_1( + _i5.TopLevelVariable context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); @@ -751,7 +701,7 @@ String __renderCategory_partial_property_6_partial_features_1( return buffer.toString(); } -String _renderCategory_partial_callable_7(_i7.ModelFunctionTyped context2, +String _renderCategory_partial_callable_6(_i6.ModelFunctionTyped context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
'''); buffer.write( - ___renderCategory_partial_typedef_8_partial_type_2_partial_categorization_0( + ___renderCategory_partial_typedef_7_partial_type_2_partial_categorization_0( context2, context1, context0)); buffer.writeln(); buffer.write(''' @@ -976,7 +926,7 @@ String __renderCategory_partial_typedef_8_partial_type_2(_i8.Typedef context2, buffer.write(context2.extendedDocLink.toString()); buffer.write('\n '); buffer.write( - ___renderCategory_partial_typedef_8_partial_type_2_partial_features_1( + ___renderCategory_partial_typedef_7_partial_type_2_partial_features_1( context2, context1, context0)); buffer.writeln(); buffer.write(''' @@ -987,8 +937,8 @@ String __renderCategory_partial_typedef_8_partial_type_2(_i8.Typedef context2, } String - ___renderCategory_partial_typedef_8_partial_type_2_partial_categorization_0( - _i8.Typedef context2, + ___renderCategory_partial_typedef_7_partial_type_2_partial_categorization_0( + _i7.Typedef context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); @@ -1006,8 +956,8 @@ String return buffer.toString(); } -String ___renderCategory_partial_typedef_8_partial_type_2_partial_features_1( - _i8.Typedef context2, +String ___renderCategory_partial_typedef_7_partial_type_2_partial_features_1( + _i7.Typedef context2, _i2.Category context1, _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); @@ -1021,7 +971,7 @@ String ___renderCategory_partial_typedef_8_partial_type_2_partial_features_1( return buffer.toString(); } -String _renderCategory_partial_search_sidebar_9( +String _renderCategory_partial_search_sidebar_8( _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
@@ -1085,7 +1035,7 @@ String _renderCategory_partial_search_sidebar_9( return buffer.toString(); } -String _renderCategory_partial_packages_10(_i1.CategoryTemplateData context0) { +String _renderCategory_partial_packages_9(_i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
    '''); var context1 = context0.localPackages; @@ -1161,7 +1111,7 @@ String _renderCategory_partial_packages_10(_i1.CategoryTemplateData context0) { return buffer.toString(); } -String _renderCategory_partial_sidebar_for_category_11( +String _renderCategory_partial_sidebar_for_category_10( _i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
      '''); @@ -1388,7 +1338,7 @@ String _renderCategory_partial_sidebar_for_category_11( return buffer.toString(); } -String _renderCategory_partial_footer_12(_i1.CategoryTemplateData context0) { +String _renderCategory_partial_footer_11(_i1.CategoryTemplateData context0) { final buffer = StringBuffer(); buffer.write(''' @@ -1438,7 +1388,7 @@ String _renderCategory_partial_footer_12(_i1.CategoryTemplateData context0) { return buffer.toString(); } -String renderClass(_i1.ClassTemplateData context0) { +String renderClass(_i1.ClassTemplateData context0) { final buffer = StringBuffer(); buffer.write(_renderClass_partial_head_0(context0)); buffer.writeln(); @@ -1822,8 +1772,7 @@ String renderClass(_i1.ClassTemplateData context0) { return buffer.toString(); } -String _renderClass_partial_head_0( - _i1.ClassTemplateData context0) { +String _renderClass_partial_head_0(_i1.ClassTemplateData context0) { final buffer = StringBuffer(); buffer.write(''' @@ -1976,8 +1925,8 @@ String _renderClass_partial_head_0( return buffer.toString(); } -String _renderClass_partial_source_link_1( - _i4.Class context1, _i1.ClassTemplateData context0) { +String _renderClass_partial_source_link_1( + _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); if (context1.hasSourceHref == true) { buffer.writeln(); @@ -1991,8 +1940,8 @@ String _renderClass_partial_source_link_1( return buffer.toString(); } -String _renderClass_partial_feature_set_2( - _i4.Class context1, _i1.ClassTemplateData context0) { +String _renderClass_partial_feature_set_2( + _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); if (context1.hasFeatureSet == true) { var context2 = context1.displayedLanguageFeatures; @@ -2008,8 +1957,8 @@ String _renderClass_partial_feature_set_2( return buffer.toString(); } -String _renderClass_partial_categorization_3( - _i4.Class context1, _i1.ClassTemplateData context0) { +String _renderClass_partial_categorization_3( + _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); if (context1.hasCategoryNames == true) { var context2 = context1.displayedCategories; @@ -2025,8 +1974,8 @@ String _renderClass_partial_categorization_3( return buffer.toString(); } -String _renderClass_partial_documentation_4( - _i4.Class context1, _i1.ClassTemplateData context0) { +String _renderClass_partial_documentation_4( + _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); if (context1.hasDocumentation == true) { buffer.writeln(); @@ -2043,8 +1992,8 @@ String _renderClass_partial_documentation_4( return buffer.toString(); } -String _renderClass_partial_property_5( - _i9.Field context2, _i4.Class context1, _i1.ClassTemplateData context0) { +String _renderClass_partial_property_5( + _i9.Field context2, _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
      '''); @@ -2117,10 +2065,8 @@ String __renderClass_partial_property_5_partial_features_1( return buffer.toString(); } -String _renderClass_partial_callable_6( - _i10.Method context2, - _i4.Class context1, - _i1.ClassTemplateData context0) { +String _renderClass_partial_callable_6( + _i10.Method context2, _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
      '''); @@ -2203,8 +2146,8 @@ String __renderClass_partial_callable_6_partial_features_1( return buffer.toString(); } -String _renderClass_partial_constant_7( - _i9.Field context2, _i4.Class context1, _i1.ClassTemplateData context0) { +String _renderClass_partial_constant_7( + _i9.Field context2, _i8.Class context1, _i1.ClassTemplateData context0) { final buffer = StringBuffer(); buffer.write('''
      '''); @@ -2277,8 +2219,7 @@ String __renderClass_partial_constant_7_partial_features_1( return buffer.toString(); } -String _renderClass_partial_search_sidebar_8( - _i1.ClassTemplateData context0) { +String _renderClass_partial_search_sidebar_8(_i1.ClassTemplateData context0) { final buffer = StringBuffer(); buffer.write('''