Fix documentation based on dartdoc's warnings (#11428)
diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart
index e50d449..b474f4a 100644
--- a/dev/tools/dartdoc.dart
+++ b/dev/tools/dartdoc.dart
@@ -10,6 +10,12 @@
import 'package:path/path.dart' as path;
import 'update_versions.dart';
+/// Whether to report all error messages (true) or attempt to filter out some
+/// known false positives (false).
+///
+/// Set this to false locally if you want to address Flutter-specific issues.
+const bool kVerbose = true; // please leave this as true on Travis
+
const String kDocRoot = 'dev/docs/doc';
/// This script expects to run with the cwd as the root of the flutter repo. It
@@ -68,8 +74,8 @@
'FLUTTER_ROOT': Directory.current.path,
},
);
- printStream(process.stdout);
- printStream(process.stderr);
+ printStream(process.stdout, prefix: 'pub:stdout: ');
+ printStream(process.stderr, prefix: 'pub:stderr: ');
final int code = await process.exitCode;
if (code != 0)
exit(code);
@@ -94,8 +100,12 @@
'--favicon=favicon.ico',
'--use-categories',
'--category-order', 'flutter,Dart Core,flutter_test,flutter_driver',
+ '--show-warnings',
+ '--auto-include-dependencies',
];
+ // Explicitly list all the packages in //flutter/packages/* that are
+ // not listed 'nodoc' in their pubspec.yaml.
for (String libraryRef in libraryRefs(diskPath: true)) {
args.add('--include-external');
args.add(libraryRef);
@@ -106,8 +116,18 @@
args,
workingDirectory: 'dev/docs',
);
- printStream(process.stdout);
- printStream(process.stderr);
+ printStream(process.stdout, prefix: 'dartdoc:stdout: ',
+ filter: kVerbose ? const <Pattern>[] : <Pattern>[
+ new RegExp(r'^generating docs for library '), // unnecessary verbosity
+ new RegExp(r'^pars'), // unnecessary verbosity
+ ],
+ );
+ printStream(process.stderr, prefix: 'dartdoc:stderr: ',
+ filter: kVerbose ? const <Pattern>[] : <Pattern>[
+ new RegExp(r'^ warning: generic type handled as HTML:'), // https://github.com/dart-lang/dartdoc/issues/1475
+ new RegExp(r'^ warning: .+: \(.+/\.pub-cache/hosted/pub.dartlang.org/.+\)'), // packages outside our control
+ ],
+ );
final int exitCode = await process.exitCode;
if (exitCode != 0)
@@ -194,15 +214,17 @@
void addHtmlBaseToIndex() {
final File indexFile = new File('$kDocRoot/index.html');
String indexContents = indexFile.readAsStringSync();
- indexContents = indexContents.replaceFirst('</title>\n',
- '</title>\n <base href="./flutter/">\n');
+ indexContents = indexContents.replaceFirst(
+ '</title>\n',
+ '</title>\n <base href="./flutter/">\n',
+ );
indexContents = indexContents.replaceAll(
'href="Android/Android-library.html"',
- 'href="https://docs.flutter.io/javadoc/"'
+ 'href="/javadoc/"',
);
indexContents = indexContents.replaceAll(
'href="iOS/iOS-library.html"',
- 'href="https://docs.flutter.io/objcdoc/"'
+ 'href="/objcdoc/"',
);
indexFile.writeAsStringSync(indexContents);
@@ -257,9 +279,14 @@
}
}
-void printStream(Stream<List<int>> stream) {
+void printStream(Stream<List<int>> stream, { String prefix: '', List<Pattern> filter: const <Pattern>[] }) {
+ assert(prefix != null);
+ assert(filter != null);
stream
.transform(UTF8.decoder)
.transform(const LineSplitter())
- .listen(print);
+ .listen((String line) {
+ if (!filter.any((Pattern pattern) => line.contains(pattern)))
+ print('$prefix$line'.trim());
+ });
}
diff --git a/dev/tools/java_and_objc_doc.dart b/dev/tools/java_and_objc_doc.dart
index f02f9d7..0998678 100644
--- a/dev/tools/java_and_objc_doc.dart
+++ b/dev/tools/java_and_objc_doc.dart
@@ -13,21 +13,16 @@
/// This script downloads an archive of Javadoc and objc doc for the engine from
/// the artifact store and extracts them to the location used for Dartdoc.
Future<Null> main(List<String> args) async {
- final String engineVersion =
- new File('bin/internal/engine.version').readAsStringSync().trim();
+ final String engineVersion = new File('bin/internal/engine.version').readAsStringSync().trim();
- final String javadocUrl =
- 'https://storage.googleapis.com/flutter_infra/flutter/$engineVersion/android-javadoc.zip';
+ final String javadocUrl = 'https://storage.googleapis.com/flutter_infra/flutter/$engineVersion/android-javadoc.zip';
generateDocs(javadocUrl, 'javadoc', 'io/flutter/view/FlutterView.html');
- final String objcdocUrl =
- 'https://storage.googleapis.com/flutter_infra/flutter/$engineVersion/ios-objcdoc.zip';
- generateDocs(
- objcdocUrl, 'objcdoc', 'Classes/FlutterViewController.html');
+ final String objcdocUrl = 'https://storage.googleapis.com/flutter_infra/flutter/$engineVersion/ios-objcdoc.zip';
+ generateDocs(objcdocUrl, 'objcdoc', 'Classes/FlutterViewController.html');
}
-Future<Null> generateDocs(
- final String url, String docName, String checkFile) async {
+Future<Null> generateDocs(String url, String docName, String checkFile) async {
final http.Response response = await http.get(url);
final Archive archive = new ZipDecoder().decodeBytes(response.bodyBytes);
