Clean up examples in analyzer docs that were using deprecated APIs and add a test to catch future breakages

Change-Id: I74bdb4c7474d130ae87e7cdc5991d7fadc79e453
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/103465
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Brian Wilkerson <[email protected]>

Author: bwilkerson

pkg/analyzer/doc/tutorial/analysis.md

@@ -24,9 +24,14 @@ to analyze.
 main() {
   List<String> includedPaths = <String>[/* ... */];
   AnalysisContextCollection collection =
-      new AnalysisContextCollection(includedPaths);
+      new AnalysisContextCollection(includedPaths: includedPaths);
   analyzeSomeFiles(collection, includedPaths);
 }
+
+analyzeSomeFiles(
+    AnalysisContextCollection collection, List<String> includedPaths) {
+  // See below.
+}
 ```
 
 The collection will create one or more analysis contexts that can be used to
@@ -52,6 +57,10 @@ analyzeSomeFiles(
     analyzeSingleFile(context, path);
   }
 }
+
+analyzeSingleFile(AnalysisContext context, String path) {
+  // See below.
+}
 ```
 
 ## Analyzing Multiple Files
@@ -68,6 +77,10 @@ analyzeAllFiles(AnalysisContextCollection collection) {
     }
   }
 }
+
+analyzeSingleFile(AnalysisContext context, String path) {
+  // See below.
+}
 ```
 
 The files returned this way will include _all_ of the files in all of the

pkg/analyzer/doc/tutorial/ast.md

@@ -50,21 +50,12 @@ If you have followed the steps in [Performing Analysis][analysis], and you want
 to get the compilation unit for a file at a known `path`, then you can ask the
 analysis session for an AST.
 
-If you need an unresolved AST, then you can use either a synchronous or
-asynchronous method to access the AST:
+If you need an unresolved AST, then you can use the following method to access
+the AST:
 
 ```dart
-main() async {
-  ParseResult result = await session.getParsedAst(path);
-  CompilationUnit unit = result.unit;
-}
-```
-
-or
-
-```dart
-main() {
-  ParseResult result = session.getParsedAstSync(path);
+processFile(AnalysisSession session, String path) {
+  ParsedUnitResult result = session.getParsedUnit(path);
   CompilationUnit unit = result.unit;
 }
 ```
@@ -73,8 +64,8 @@ If you need a resolved AST, then you need to use the following asynchronous
 method to access it:
 
 ```dart
-main() async {
-  ResolveResult result = await session.getResolvedAst(path);
+processFile(AnalysisSession session, String path) async {
+  ResolvedUnitResult result = await session.getResolvedUnit(path);
   CompilationUnit unit = result.unit;
 }
 ```

pkg/analyzer/test/snippets/README.md

@@ -0,0 +1 @@
+The 'snippets' directory exists to enable the test in 'verify_docs_test.dart'.

pkg/analyzer/test/test_all.dart

@@ -13,6 +13,7 @@ import 'instrumentation/test_all.dart' as instrumentation;
 import 'parse_compilation_unit_test.dart' as parse_compilation_unit;
 import 'source/test_all.dart' as source;
 import 'src/test_all.dart' as src;
+import 'verify_docs_test.dart' as verify_docs;
 import 'verify_tests_test.dart' as verify_tests;
 
 main() {
@@ -26,6 +27,7 @@ main() {
     parse_compilation_unit.main();
     source.main();
     src.main();
+    verify_docs.main();
     verify_tests.main();
   }, name: 'analyzer');
 }

pkg/analyzer/test/verify_docs_test.dart

@@ -0,0 +1,153 @@
+// Copyright (c) 2019, 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 'dart:convert';
+
+import 'package:analyzer/dart/analysis/analysis_context.dart';
+import 'package:analyzer/dart/analysis/analysis_context_collection.dart';
+import 'package:analyzer/dart/analysis/results.dart';
+import 'package:analyzer/error/error.dart';
+import 'package:analyzer/file_system/file_system.dart';
+import 'package:analyzer/file_system/overlay_file_system.dart';
+import 'package:analyzer/file_system/physical_file_system.dart';
+import 'package:analyzer/src/error/codes.dart';
+import 'package:front_end/src/testing/package_root.dart' as package_root;
+import 'package:test/test.dart';
+
+main() async {
+  SnippetTester tester = SnippetTester();
+  await tester.verify();
+  if (tester.output.isNotEmpty) {
+    fail(tester.output.toString());
+  }
+}
+
+class SnippetTester {
+  OverlayResourceProvider provider;
+  Folder docFolder;
+  String snippetDirPath;
+  String snippetPath;
+
+  StringBuffer output = StringBuffer();
+
+  SnippetTester() {
+    provider = OverlayResourceProvider(PhysicalResourceProvider.INSTANCE);
+    String packageRoot =
+        provider.pathContext.normalize(package_root.packageRoot);
+    String analyzerPath = provider.pathContext.join(packageRoot, 'analyzer');
+    String docPath = provider.pathContext.join(analyzerPath, 'doc');
+    docFolder = provider.getFolder(docPath);
+    snippetDirPath =
+        provider.pathContext.join(analyzerPath, 'test', 'snippets');
+    snippetPath = provider.pathContext.join(snippetDirPath, 'snippet.dart');
+  }
+
+  void verify() async {
+    await verifyFolder(docFolder);
+  }
+
+  void verifyFile(File file) async {
+    String content = file.readAsStringSync();
+    List<String> lines = const LineSplitter().convert(content);
+    List<String> codeLines = [];
+    bool inCode = false;
+    for (int i = 0; i < lines.length; i++) {
+      String line = lines[i];
+      if (line == '```dart') {
+        if (inCode) {
+          // TODO(brianwilkerson) Report this.
+        }
+        inCode = true;
+      } else if (line == '```') {
+        if (!inCode) {
+          // TODO(brianwilkerson) Report this.
+        }
+        await verifySnippet(file, codeLines.join('\n'));
+        codeLines.clear();
+        inCode = false;
+      } else if (inCode) {
+        codeLines.add(line);
+      }
+    }
+  }
+
+  void verifyFolder(Folder folder) async {
+    for (Resource child in folder.getChildren()) {
+      if (child is File) {
+        if (child.shortName.endsWith('.md')) {
+          await verifyFile(child);
+        }
+      } else if (child is Folder) {
+        await verifyFolder(child);
+      }
+    }
+  }
+
+  void verifySnippet(File file, String snippet) async {
+    // TODO(brianwilkerson) When the files outside of 'src' contain only public
+    //  API, write code to compute the list of imports so that new public API
+    //  will automatically be allowed.
+    String imports = '''
+import 'dart:math' as math;
+
+import 'package:analyzer/dart/analysis/analysis_context.dart';
+import 'package:analyzer/dart/analysis/analysis_context_collection.dart';
+import 'package:analyzer/dart/analysis/results.dart';
+import 'package:analyzer/dart/analysis/session.dart';
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/dart/element/visitor.dart';
+
+''';
+    provider.setOverlay(snippetPath,
+        content: '''
+$imports
+$snippet
+''',
+        modificationStamp: 1);
+    try {
+      AnalysisContextCollection collection = new AnalysisContextCollection(
+          includedPaths: <String>[snippetDirPath], resourceProvider: provider);
+      List<AnalysisContext> contexts = collection.contexts;
+      if (contexts.length != 1) {
+        fail('The snippets directory contains multiple analysis contexts.');
+      }
+      ErrorsResult results =
+          await contexts[0].currentSession.getErrors(snippetPath);
+      Iterable<AnalysisError> errors = results.errors.where((error) {
+        ErrorCode errorCode = error.errorCode;
+        return errorCode != HintCode.UNUSED_IMPORT &&
+            errorCode != HintCode.UNUSED_LOCAL_VARIABLE;
+      });
+      if (errors.isNotEmpty) {
+        String filePath =
+            provider.pathContext.relative(file.path, from: docFolder.path);
+        if (output.isNotEmpty) {
+          output.writeln();
+        }
+        output.writeln('Errors in snippet in "$filePath":');
+        output.writeln();
+        output.writeln(snippet);
+        output.writeln();
+        int importsLength = imports.length + 1; // account for the '\n'.
+        for (var error in errors) {
+          writeError(error, importsLength);
+        }
+      }
+    } finally {
+      provider.removeOverlay(snippetPath);
+    }
+  }
+
+  void writeError(AnalysisError error, int prefixLength) {
+    output.write(error.errorCode);
+    output.write(' (');
+    output.write(error.offset - prefixLength);
+    output.write(', ');
+    output.write(error.length);
+    output.write(') ');
+    output.writeln(error.message);
+  }
+}