Skip to content

API docs generation fails when using Dart 3 features #127320

@TahaTesser

Description

@TahaTesser

Is there an existing issue for this?

Steps to reproduce

  1. Clone the Flutter repository to update a code sample (git clone [email protected]:flutter/flutter.git)
  2. Navigate to flutter/examples/api and edit any code sample by adding a Dart 3 feature
  3. Then go to flutter/dev/bots and execute sh doc.sh to generate documentation locally.

For instance, add this line from https://dart.dev/language/records in any code sample.

var record = ('first', a: 2, b: true, 'last');

Following packages are used in doc generation script

dartdoc version: 6.2.2
snippets version: 0.3.0
flutter version: 3.11.0-10.0.pre.44

While dartdoc and flutter version support Dart 3, the snippets package isn't updated to Dart 3.

There is no error when removing Dart 3 feature.

Expected results

Documentation generation doesn't fail with Dart 3 features in an API sample

Actual results

Documentation generation fails with Dart 3 features in an API sample

Code sample

Code sample
var record = ('first', a: 2, b: true, 'last');

Screenshots or Video

Screenshots / Video demonstration

[Upload media here]

Logs

Logs
pub:stdout: Got dependencies!
Copied dev/docs/assets/overrides.css to dev/docs/doc/assets/overrides.css
Copied dev/docs/assets/snippets.css to dev/docs/doc/assets/snippets.css
Copied dev/docs/assets/api_survey.js to dev/docs/doc/assets/api_survey.js
Copied dev/docs/assets/snippets.js to dev/docs/doc/assets/snippets.js

dartdoc version: 6.2.2
snippets version: 0.3.0
flutter version: 3.11.0-10.0.pre.44

Executing: (cd dev/docs ; /Users/tahatesser/Code/flutter/bin/cache/dart-sdk/bin/dart global run dartdoc --allow-tools --no-validate-links --link-to-source-excludes ../../bin/cache --link-to-source-root ../.. --link-to-source-uri-template https://github.com/flutter/flutter/blob/master/%f%#L%l% --inject-html --use-base-href --header styles.html --header analytics.html --header survey.html --header snippets.html --header opensearch.html --footer-text lib/footer.html --allow-warnings-in-packages Flutter,platform_integration,flutter_web_plugins,integration_test,flutter_goldens,flutter,flutter_localizations,flutter_driver,flutter_test --exclude-packages analyzer,args,barback,csslib,flutter_goldens,flutter_goldens_client,front_end,fuchsia_remote_debug_protocol,glob,html,http_multi_server,io,isolate,js,kernel,logging,mime,mockito,node_preamble,plugin,shelf,shelf_packages_handler,shelf_static,shelf_web_socket,utf,watcher,yaml --exclude dart:io/network_policy.dart,package:Flutter/temp_doc.dart,package:http/browser_client.dart,package:intl/intl_browser.dart,package:matcher/mirror_matchers.dart,package:quiver/io.dart,package:quiver/mirrors.dart,package:vm_service_client/vm_service_client.dart,package:web_socket_channel/html.dart --favicon=favicon.ico --package-order flutter,Dart,platform_integration,flutter_test,flutter_driver --auto-include-dependencies)
dartdoc:stdout: Documenting Flutter...
dartdoc:stderr:   error: tool execution failed: Tool "dartpad" returned non-zero exit code (1) when run as "/Users/tahatesser/Code/flutter/bin/cache/dart-sdk/bin/dart pub global run snippets --output-directory=doc/snippets --type=dartpad" from /Users/tahatesser/Code/flutter/dev/docs
dartdoc:stderr: Input to dartpad was:
dartdoc:stderr: This sample produces an enabled and a disabled ElevatedButton.
dartdoc:stderr:
dartdoc:stderr: ** See code in examples/api/lib/material/elevated_button/elevated_button.0.dart **
dartdoc:stderr: Stderr output was:
dartdoc:stderr: Code to format:
dartdoc:stderr:     1: import 'package:flutter/material.dart';
dartdoc:stderr:     2:
dartdoc:stderr:     3: /// Flutter code sample for [ElevatedButton].
dartdoc:stderr:     4:
dartdoc:stderr:     5: void main() => runApp(const ElevatedButtonExampleApp());
dartdoc:stderr:     6:
dartdoc:stderr:     7: class ElevatedButtonExampleApp extends StatelessWidget {
dartdoc:stderr:     8:   const ElevatedButtonExampleApp({super.key});
dartdoc:stderr:     9:
dartdoc:stderr:    10:   @override
dartdoc:stderr:    11:   Widget build(BuildContext context) {
dartdoc:stderr:    12:     return MaterialApp(
dartdoc:stderr:    13:       home: Scaffold(
dartdoc:stderr:    14:         appBar: AppBar(title: const Text('ElevatedButton Sample')),
dartdoc:stderr:    15:         body: const ElevatedButtonExample(),
dartdoc:stderr:    16:       ),
dartdoc:stderr:    17:     );
dartdoc:stderr:    18:   }
dartdoc:stderr:    19: }
dartdoc:stderr:    20:
dartdoc:stderr:    21: class ElevatedButtonExample extends StatefulWidget {
dartdoc:stderr:    22:   const ElevatedButtonExample({super.key});
dartdoc:stderr:    23:
dartdoc:stderr:    24:   @override
dartdoc:stderr:    25:   State<ElevatedButtonExample> createState() => _ElevatedButtonExampleState();
dartdoc:stderr:    26: }
dartdoc:stderr:    27:
dartdoc:stderr:    28: class _ElevatedButtonExampleState extends State<ElevatedButtonExample> {
dartdoc:stderr:    29:
dartdoc:stderr:    30:   @override
dartdoc:stderr:    31:   Widget build(BuildContext context) {
dartdoc:stderr:    32:     final ButtonStyle style = ElevatedButton.styleFrom(textStyle: const TextStyle(fontSize: 20));
dartdoc:stderr:    33: var record = ('first', a: 2, b: true, 'last');
dartdoc:stderr:    34:
dartdoc:stderr:    35:     return Center(
dartdoc:stderr:    36:       child: Column(
dartdoc:stderr:    37:         mainAxisSize: MainAxisSize.min,
dartdoc:stderr:    38:         children: <Widget>[
dartdoc:stderr:    39:           ElevatedButton(
dartdoc:stderr:    40:             style: style,
dartdoc:stderr:    41:             onPressed: null,
dartdoc:stderr:    42:             child: const Text('Disabled'),
dartdoc:stderr:    43:           ),
dartdoc:stderr:    44:           const SizedBox(height: 30),
dartdoc:stderr:    45:           ElevatedButton(
dartdoc:stderr:    46:             style: style,
dartdoc:stderr:    47:             onPressed: () {},
dartdoc:stderr:    48:             child: const Text('Enabled'),
dartdoc:stderr:    49:           ),
dartdoc:stderr:    50:         ],
dartdoc:stderr:    51:       ),
dartdoc:stderr:    52:     );
dartdoc:stderr:    53:   }
dartdoc:stderr:    54: }
dartdoc:stderr:
dartdoc:stderr: Unable to format sample code: Could not format because the source could not be parsed:
dartdoc:stderr:
dartdoc:stderr: line 33, column 14 of .: This requires the 'records' language feature to be enabled.
dartdoc:stderr:    ╷
dartdoc:stderr: 33 │ var record = ('first', a: 2, b: true, 'last');
dartdoc:stderr:    │              ^
dartdoc:stderr:    ╵
dartdoc:stderr:
dartdoc:stderr:
dartdoc:stderr:     from material.ElevatedButton: (file:///Users/tahatesser/Code/flutter/packages/flutter/lib/src/material/elevated_button.dart:63:7)
dartdoc:stdout: Initialized dartdoc with 1207 libraries
dartdoc:stdout: Generating docs for library material from package:flutter/material.dart...
dartdoc:stdout: Generating docs for library foundation from package:flutter/foundation.dart...
dartdoc:stdout: Generating docs for library widgets from package:flutter/widgets.dart...
dartdoc:stdout: Generating docs for library gestures from package:flutter/gestures.dart...
dartdoc:stdout: Generating docs for library painting from package:flutter/painting.dart...
dartdoc:stdout: Generating docs for library physics from package:flutter/physics.dart...
dartdoc:stdout: Generating docs for library cupertino from package:flutter/cupertino.dart...
dartdoc:stdout: Generating docs for library semantics from package:flutter/semantics.dart...
dartdoc:stdout: Generating docs for library rendering from package:flutter/rendering.dart...
dartdoc:stdout: Generating docs for library scheduler from package:flutter/scheduler.dart...
dartdoc:stdout: Generating docs for library animation from package:flutter/animation.dart...
dartdoc:stdout: Generating docs for library services from package:flutter/services.dart...
dartdoc:stdout: Generating docs for library dart:ui from dart:ui...
dartdoc:stdout: Generating docs for library dart:developer from dart:developer...
dartdoc:stdout: Generating docs for library dart:collection from dart:collection...
dartdoc:stdout: Generating docs for library dart:ui_web from dart:ui_web...
dartdoc:stdout: Generating docs for library dart:core from dart:core...
dartdoc:stdout: Generating docs for library dart:isolate from dart:isolate...
dartdoc:stdout: Generating docs for library dart:js from dart:js...
dartdoc:stdout: Generating docs for library dart:js_interop from dart:js_interop...
dartdoc:stdout: Generating docs for library dart:js_interop_unsafe from dart:js_interop_unsafe...
dartdoc:stdout: Generating docs for library dart:async from dart:async...
dartdoc:stdout: Generating docs for library dart:io from dart:io...
dartdoc:stdout: Generating docs for library dart:html from dart:html...
dartdoc:stdout: Generating docs for library dart:math from dart:math...
dartdoc:stdout: Generating docs for library dart:js_util from dart:js_util...
dartdoc:stdout: Generating docs for library dart:ffi from dart:ffi...
dartdoc:stdout: Generating docs for library dart:typed_data from dart:typed_data...
dartdoc:stdout: Generating docs for library dart:convert from dart:convert...
dartdoc:stdout: Generating docs for library iOS from package:platform_integration/ios.dart...
dartdoc:stdout: Generating docs for library Android from package:platform_integration/android.dart...
dartdoc:stdout: Generating docs for library flutter_test from package:flutter_test/flutter_test.dart...
dartdoc:stdout: Generating docs for library flutter_driver from package:flutter_driver/flutter_driver.dart...
dartdoc:stdout: Generating docs for library flutter_driver_extension from package:flutter_driver/driver_extension.dart...
dartdoc:stdout: Generating docs for library flutter_localizations from package:flutter_localizations/flutter_localizations.dart...
dartdoc:stdout: Generating docs for library flutter_web_plugins from package:flutter_web_plugins/flutter_web_plugins.dart...
dartdoc:stdout: Generating docs for library url_strategy from package:flutter_web_plugins/url_strategy.dart...
dartdoc:stdout: Generating docs for library async from package:async/async.dart...
dartdoc:stdout: Generating docs for library boolean_selector from package:boolean_selector/boolean_selector.dart...
dartdoc:stdout: Generating docs for library characters from package:characters/characters.dart...
dartdoc:stdout: Generating docs for library clock from package:clock/clock.dart...
dartdoc:stdout: Generating docs for library collection from package:collection/collection.dart...
dartdoc:stdout: Generating docs for library dart.pkg.collection.iterable_zip from package:collection/iterable_zip.dart...
dartdoc:stdout: Generating docs for library dart.pkg.collection.priority_queue from package:collection/priority_queue.dart...
dartdoc:stdout: Generating docs for library dart.pkg.collection.equality from package:collection/equality.dart...
dartdoc:stdout: Generating docs for library dart.pkg.collection.algorithms from package:collection/algorithms.dart...
dartdoc:stdout: Generating docs for library dart.pkg.collection.wrappers from package:collection/wrappers.dart...
dartdoc:stdout: Generating docs for library crypto from package:crypto/crypto.dart...
dartdoc:stdout: Generating docs for library fake_async from package:fake_async/fake_async.dart...
dartdoc:stdout: Generating docs for library local from package:file/local.dart...
dartdoc:stdout: Generating docs for library chroot from package:file/chroot.dart...
dartdoc:stdout: Generating docs for library memory from package:file/memory.dart...
dartdoc:stdout: Generating docs for library file from package:file/file.dart...
dartdoc:stdout: Generating docs for library integration_test_driver from package:integration_test/integration_test_driver.dart...
dartdoc:stdout: Generating docs for library integration_test_driver_extended from package:integration_test/integration_test_driver_extended.dart...
dartdoc:stdout: Generating docs for library _extension_web from package:integration_test/_extension_web.dart...
dartdoc:stdout: Generating docs for library _extension_io from package:integration_test/_extension_io.dart...
dartdoc:stdout: Generating docs for library _callback_io from package:integration_test/_callback_io.dart...
dartdoc:stdout: Generating docs for library common from package:integration_test/common.dart...
dartdoc:stdout: Generating docs for library integration_test from package:integration_test/integration_test.dart...
dartdoc:stdout: Generating docs for library _callback_web from package:integration_test/_callback_web.dart...
dartdoc:stdout: Generating docs for library intl from package:intl/intl.dart...
dartdoc:stdout: Generating docs for library date_symbol_data_http_request from package:intl/date_symbol_data_http_request.dart...
dartdoc:stdout: Generating docs for library message_lookup_by_library from package:intl/message_lookup_by_library.dart...
dartdoc:stdout: Generating docs for library message_format from package:intl/message_format.dart...
dartdoc:stdout: Generating docs for library intl_standalone from package:intl/intl_standalone.dart...
dartdoc:stdout: Generating docs for library date_symbol_data_custom from package:intl/date_symbol_data_custom.dart...
dartdoc:stdout: Generating docs for library date_symbol_data_local from package:intl/date_symbol_data_local.dart...
dartdoc:stdout: Generating docs for library date_symbols from package:intl/date_symbols.dart...
dartdoc:stdout: Generating docs for library locale from package:intl/locale.dart...
dartdoc:stdout: Generating docs for library number_symbol_data from package:intl/number_symbols_data.dart...
dartdoc:stdout: Generating docs for library date_time_patterns from package:intl/date_time_patterns.dart...
dartdoc:stdout: Generating docs for library date_symbol_data_file from package:intl/date_symbol_data_file.dart...
dartdoc:stdout: Generating docs for library number_symbols from package:intl/number_symbols.dart...
dartdoc:stdout: Generating docs for library matcher from package:matcher/matcher.dart...
dartdoc:stdout: Generating docs for library expect from package:matcher/expect.dart...
dartdoc:stdout: Generating docs for library variant from package:material_color_utilities/scheme/variant.dart...
dartdoc:stdout: Generating docs for library scheme_content from package:material_color_utilities/scheme/scheme_content.dart...
dartdoc:stdout: Generating docs for library dynamic_scheme from package:material_color_utilities/scheme/dynamic_scheme.dart...
dartdoc:stdout: Generating docs for library scheme_expressive from package:material_color_utilities/scheme/scheme_expressive.dart...
dartdoc:stdout: Generating docs for library scheme_vibrant from package:material_color_utilities/scheme/scheme_vibrant.dart...
dartdoc:stdout: Generating docs for library scheme_monochrome from package:material_color_utilities/scheme/scheme_monochrome.dart...
dartdoc:stdout: Generating docs for library scheme_neutral from package:material_color_utilities/scheme/scheme_neutral.dart...
dartdoc:stdout: Generating docs for library scheme_fidelity from package:material_color_utilities/scheme/scheme_fidelity.dart...
dartdoc:stdout: Generating docs for library scheme_tonal_spot from package:material_color_utilities/scheme/scheme_tonal_spot.dart...
dartdoc:stdout: Generating docs for library scheme from package:material_color_utilities/scheme/scheme.dart...
dartdoc:stdout: Generating docs for library dislike_analyzer from package:material_color_utilities/dislike/dislike_analyzer.dart...
dartdoc:stdout: Generating docs for library quantizer_wu from package:material_color_utilities/quantize/quantizer_wu.dart...
dartdoc:stdout: Generating docs for library quantizer_wsmeans from package:material_color_utilities/quantize/quantizer_wsmeans.dart...
dartdoc:stdout: Generating docs for library quantizer_map from package:material_color_utilities/quantize/quantizer_map.dart...
dartdoc:stdout: Generating docs for library quantizer_celebi from package:material_color_utilities/quantize/quantizer_celebi.dart...
dartdoc:stdout: Generating docs for library quantizer from package:material_color_utilities/quantize/quantizer.dart...
dartdoc:stdout: Generating docs for library point_provider_lab from package:material_color_utilities/quantize/src/point_provider_lab.dart...
dartdoc:stdout: Generating docs for library point_provider from package:material_color_utilities/quantize/src/point_provider.dart...
dartdoc:stdout: Generating docs for library hct from package:material_color_utilities/hct/hct.dart...
dartdoc:stdout: Generating docs for library viewing_conditions from package:material_color_utilities/hct/viewing_conditions.dart...
dartdoc:stdout: Generating docs for library cam16 from package:material_color_utilities/hct/cam16.dart...
dartdoc:stdout: Generating docs for library hct_solver from package:material_color_utilities/hct/src/hct_solver.dart...
dartdoc:stdout: Generating docs for library color_utils from package:material_color_utilities/utils/color_utils.dart...
dartdoc:stdout: Generating docs for library math_utils from package:material_color_utilities/utils/math_utils.dart...
dartdoc:stdout: Generating docs for library string_utils from package:material_color_utilities/utils/string_utils.dart...
dartdoc:stdout: Generating docs for library blend from package:material_color_utilities/blend/blend.dart...
dartdoc:stdout: Generating docs for library score from package:material_color_utilities/score/score.dart...
dartdoc:stdout: Generating docs for library material_dynamic_colors from package:material_color_utilities/dynamiccolor/material_dynamic_colors.dart...
dartdoc:stdout: Generating docs for library dynamic_color from package:material_color_utilities/dynamiccolor/dynamic_color.dart...
dartdoc:stdout: Generating docs for library tone_delta_constraint from package:material_color_utilities/dynamiccolor/src/tone_delta_constraint.dart...
dartdoc:stdout: Generating docs for library contrast from package:material_color_utilities/contrast/contrast.dart...
dartdoc:stdout: Generating docs for library material_color_utilities from package:material_color_utilities/material_color_utilities.dart...
dartdoc:stdout: Generating docs for library temperature_cache from package:material_color_utilities/temperature/temperature_cache.dart...
dartdoc:stdout: Generating docs for library tonal_palette from package:material_color_utilities/palettes/tonal_palette.dart...
dartdoc:stdout: Generating docs for library core_palette from package:material_color_utilities/palettes/core_palette.dart...
dartdoc:stdout: Generating docs for library meta from package:meta/meta.dart...
dartdoc:stdout: Generating docs for library meta_dart2js from package:meta/dart2js.dart...
dartdoc:stdout: Generating docs for library meta_meta from package:meta/meta_meta.dart...
dartdoc:stdout: Generating docs for library path from package:path/path.dart...
dartdoc:stdout: Generating docs for library platform from package:platform/platform.dart...
dartdoc:stdout: Generating docs for library process from package:process/process.dart...
dartdoc:stdout: Generating docs for library source_span from package:source_span/source_span.dart...
dartdoc:stdout: Generating docs for library stack_trace from package:stack_trace/stack_trace.dart...
dartdoc:stdout: Generating docs for library stream_channel from package:stream_channel/stream_channel.dart...
dartdoc:stdout: Generating docs for library isolate_channel from package:stream_channel/isolate_channel.dart...
dartdoc:stdout: Generating docs for library string_scanner from package:string_scanner/string_scanner.dart...
dartdoc:stdout: Generating docs for library sync.http from package:sync_http/sync_http.dart...
dartdoc:stdout: Generating docs for library term_glyph from package:term_glyph/term_glyph.dart...
dartdoc:stdout: Generating docs for library backend from package:test_api/backend.dart...
dartdoc:stdout: Generating docs for library hooks_testing from package:test_api/hooks_testing.dart...
dartdoc:stdout: Generating docs for library hooks from package:test_api/hooks.dart...
dartdoc:stdout: Generating docs for library test_api from package:test_api/test_api.dart...
dartdoc:stdout: Generating docs for library expect from package:test_api/expect.dart...
dartdoc:stdout: Generating docs for library test_api.fake from package:test_api/fake.dart...
dartdoc:stdout: Generating docs for library test_api.scaffolding from package:test_api/scaffolding.dart...
dartdoc:stdout: Generating docs for library typed_data.typed_buffers from package:typed_data/typed_buffers.dart...
dartdoc:stdout: Generating docs for library typed_data from package:typed_data/typed_data.dart...
dartdoc:stdout: Generating docs for library vector_math_lists from package:vector_math/vector_math_lists.dart...
dartdoc:stdout: Generating docs for library hash from package:vector_math/hash.dart...
dartdoc:stdout: Generating docs for library vector_math_geometry from package:vector_math/vector_math_geometry.dart...
dartdoc:stdout: Generating docs for library vector_math from package:vector_math/vector_math.dart...
dartdoc:stdout: Generating docs for library vector_math_operations from package:vector_math/vector_math_operations.dart...
dartdoc:stdout: Generating docs for library vector_math_64 from package:vector_math/vector_math_64.dart...
dartdoc:stdout: Generating docs for library vm_service_io from package:vm_service/vm_service_io.dart...
dartdoc:stdout: Generating docs for library utils from package:vm_service/utils.dart...
dartdoc:stdout: Generating docs for library vm_service from package:vm_service/vm_service.dart...
dartdoc:stdout: Generating docs for library async_io from package:webdriver/async_io.dart...
dartdoc:stdout: Generating docs for library core from package:webdriver/core.dart...
dartdoc:stdout: Generating docs for library sync_io from package:webdriver/sync_io.dart...
dartdoc:stdout: Generating docs for library io from package:webdriver/io.dart...
dartdoc:stdout: Generating docs for library async from package:webdriver/support/async.dart...
dartdoc:stdout: Generating docs for library stdio_stepper from package:webdriver/support/stdio_stepper.dart...
dartdoc:stdout: Generating docs for library firefox_profile from package:webdriver/support/firefox_profile.dart...
dartdoc:stdout: Generating docs for library async_core from package:webdriver/async_core.dart...
dartdoc:stdout: Generating docs for library sync_core from package:webdriver/sync_core.dart...
dartdoc:stdout: Generating docs for library async_html from package:webdriver/async_html.dart...
dartdoc:stderr: Found 0 warnings and 1 error.
dartdoc:stdout: Documented 152 public libraries in 370.2 seconds
dartdoc:stderr:
dartdoc:stderr: dartdoc 6.2.2 (/Users/tahatesser/.pub-cache/global_packages/dartdoc/bin/dartdoc.dart-3.1.0-129.0.dev.snapshot) failed: encountered 1 errors.

Flutter Doctor output

Doctor output
[Paste your output here]

Metadata

Metadata

Labels

c: contributor-productivityTeam-specific productivity, code health, technical debt.c: tech-debtTechnical debt, code quality, testing, etc.d: api docsIssues with https://api.flutter.dev/frameworkflutter/packages/flutter repository. See also f: labels.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions