diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml index 531236d41b..28d7b64bc3 100644 --- a/dartdoc_options.yaml +++ b/dartdoc_options.yaml @@ -13,24 +13,23 @@ dartdoc: command: ["dev/snippets/lib/main.dart", "--type=sample", "--dartpad"] description: "Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad." errors: - # The following are always errors: + # Default errors of dartdoc: - duplicate-file - invalid-parameter - tool-error - unresolved-export - # The following are elevated from warnings because we currently don't - # fail on warnings: + # Warnings that are elevated to errors: - ambiguous-doc-reference - ambiguous-reexport - - ignored-canonical-for - - no-canonical-found - - not-implemented - - no-library-level-docs - - category-order-gives-missing-package-name - - reexported-private-api-across-packages - # - unresolved-doc-reference # Too many failures, needs clean-up - broken-link - - unknown-macro - - orphaned-file - - unknown-file + - category-order-gives-missing-package-name + - ignored-canonical-for - missing-from-search-index + - no-canonical-found + - no-library-level-docs + - not-implemented + - reexported-private-api-across-packages + - unknown-macro + - unknown-file + - unresolved-doc-reference + - orphaned-file diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart index 91d06deca9..67825e0597 100644 --- a/dev/tools/dartdoc.dart +++ b/dev/tools/dartdoc.dart @@ -17,6 +17,9 @@ const String kDocsRoot = 'dev/docs'; const String kPublishRoot = '$kDocsRoot/doc'; const String kSnippetsRoot = 'dev/snippets'; +const String kDummyPackageName = 'Flutter'; +const String kPlatformIntegrationPackageName = 'platform_integration'; + /// This script expects to run with the cwd as the root of the flutter repo. It /// will generate documentation for the packages in `//packages/` and write the /// documentation to `//dev/docs/doc/api/`. @@ -50,7 +53,7 @@ Future main(List arguments) async { // Create the pubspec.yaml file. final StringBuffer buf = StringBuffer(); - buf.writeln('name: Flutter'); + buf.writeln('name: $kDummyPackageName'); buf.writeln('homepage: https://flutter.dev'); // TODO(dnfield): Re-factor for proper versioning, https://github.com/flutter/flutter/issues/55409 buf.writeln('version: 0.0.0'); @@ -59,10 +62,10 @@ Future main(List arguments) async { buf.writeln(' $package:'); buf.writeln(' sdk: flutter'); } - buf.writeln(' platform_integration: 0.0.1'); + buf.writeln(' $kPlatformIntegrationPackageName: 0.0.1'); buf.writeln('dependency_overrides:'); - buf.writeln(' platform_integration:'); - buf.writeln(' path: platform_integration'); + buf.writeln(' $kPlatformIntegrationPackageName:'); + buf.writeln(' path: $kPlatformIntegrationPackageName'); File('$kDocsRoot/pubspec.yaml').writeAsStringSync(buf.toString()); // Create the library file. @@ -122,6 +125,17 @@ Future main(List arguments) async { ); print('\n${result.stdout}flutter version: $version\n'); + // Dartdoc warnings and errors in these packages are considered fatal. + // All packages owned by flutter should be in the list. + // TODO(goderbauer): Figure out how to add 'dart:ui'. + final List flutterPackages = [ + kDummyPackageName, + kPlatformIntegrationPackageName, + ...findPackageNames(), + ]..remove('flutter_test'); + // TODO(goderbauer): Enable flutter_test when engine is rolled to include + // https://github.com/flutter/engine/pull/20140. + // Generate the documentation. // We don't need to exclude flutter_tools in this list because it's not in the // recursive dependencies of the package defined at dev/docs/pubspec.yaml @@ -142,10 +156,7 @@ Future main(List arguments) async { '--header', 'snippets.html', '--header', 'opensearch.html', '--footer-text', 'lib/footer.html', - '--allow-warnings-in-packages', - [ - 'flutter', - ].join(','), + '--allow-warnings-in-packages', flutterPackages.join(','), '--exclude-packages', [ 'analyzer', @@ -189,7 +200,7 @@ Future main(List arguments) async { 'package:web_socket_channel/html.dart', ].join(','), '--favicon=favicon.ico', - '--package-order', 'flutter,Dart,platform_integration,flutter_test,flutter_driver', + '--package-order', 'flutter,Dart,$kPlatformIntegrationPackageName,flutter_test,flutter_driver', '--auto-include-dependencies', ]; @@ -477,8 +488,8 @@ Iterable libraryRefs() sync* { } // Add a fake package for platform integration APIs. - yield 'platform_integration/android.dart'; - yield 'platform_integration/ios.dart'; + yield '$kPlatformIntegrationPackageName/android.dart'; + yield '$kPlatformIntegrationPackageName/ios.dart'; } void printStream(Stream> stream, { String prefix = '', List filter = const [] }) {