Add more specific deprecation notices to package:analyzer/analyzer.dart.

Also fix dev_compiler and tools/patch_sdk.dart to stop using
deprecated functions from package:analyzer/analyzer.dart.

Change-Id: I623e2e5e9cfaed6f52b6126b4eb65d8b47dd3afb
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/107140
Commit-Queue: Paul Berry <paulberry@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Reviewed-by: Vijay Menon <vsm@google.com>

pkg/analyzer/CHANGELOG.md

@@ -24,6 +24,8 @@
 * Deprecated `parseFile`.  Please use `parseFile2` instead--in addition to
   supporting the same `featureSet` and `throwIfDiagnostics` parameters as
   `parseString`, it is much more efficient than `parseFile`.
+* Added more specific deprecation notices to `package:analyzer/analyzer.dart` to
+  direct clients to suitable replacements.
 
 ## 0.36.3
 * Deprecated `AstFactory.compilationUnit`.  In a future analyzer release, this

pkg/analyzer/lib/analyzer.dart

@@ -39,7 +39,14 @@ export 'package:analyzer/src/generated/utilities_dart.dart';
 /// [suppressErrors] is `true`, in which case any errors are discarded.
 ///
 /// If [parseFunctionBodies] is [false] then only function signatures will be
-/// parsed.
+/// parsed.  (Currently broken; function bodies are always parsed).
+///
+/// Deprecated - please use the `parseString` function
+/// (from package:analyzer/dart/analysis/utilities.dart) instead.
+///
+/// Note that `parseString` does not support the `parseFunctionBodies` option;
+/// callers that don't require function bodies should simply ignore them.
+@Deprecated('Please use parseString instead')
 CompilationUnit parseCompilationUnit(String contents,
     {String name,
     bool suppressErrors: false,
@@ -58,7 +65,14 @@ CompilationUnit parseCompilationUnit(String contents,
 /// [suppressErrors] is `true`, in which case any errors are discarded.
 ///
 /// If [parseFunctionBodies] is [false] then only function signatures will be
-/// parsed.
+/// parsed.  (Currently broken; function bodies are always parsed).
+///
+/// Deprecated - please use the `parseFile2` function
+/// (from package:analyzer/dart/analysis/utilities.dart) instead.
+///
+/// Note that `parseFile2` does not support the `parseFunctionBodies` option;
+/// callers that don't require function bodies should simply ignore them.
+@Deprecated('Please use parseFile2 instead')
 CompilationUnit parseDartFile(String path,
     {bool suppressErrors: false,
     bool parseFunctionBodies: true,
@@ -83,6 +97,7 @@ CompilationUnit parseDartFile(String path,
 }
 
 /// Parses the script tag and directives in a string of Dart code into an AST.
+/// (Currently broken; the entire file is parsed).
 ///
 /// Stops parsing when the first non-directive is encountered. The rest of the
 /// string will not be parsed.
@@ -92,6 +107,13 @@ CompilationUnit parseDartFile(String path,
 ///
 /// Throws an [AnalyzerErrorGroup] if any errors occurred, unless
 /// [suppressErrors] is `true`, in which case any errors are discarded.
+///
+/// Deprecated - please use the `parseString` function
+/// (from package:analyzer/dart/analysis/utilities.dart) instead.
+///
+/// Note that `parseString` parses the whole file; callers that only require
+/// directives should simply ignore the rest of the parse result.
+@Deprecated('Please use parseString instead')
 CompilationUnit parseDirectives(String contents,
     {String name, bool suppressErrors: false, FeatureSet featureSet}) {
   // TODO(paulberry): make featureSet a required parameter.
@@ -112,6 +134,7 @@ CompilationUnit parseDirectives(String contents,
 }
 
 /// Converts an AST node representing a string literal into a [String].
+@Deprecated('Please use StringLiteral.stringValue instead')
 String stringLiteralToString(StringLiteral literal) {
   return literal.stringValue;
 }

pkg/analyzer/test/parse_compilation_unit_test.dart

@@ -8,6 +8,7 @@ import 'package:test/test.dart';
 
 void main() {
   test("parses a valid compilation unit successfully", () {
+    // ignore: deprecated_member_use_from_same_package
     var unit = parseCompilationUnit("void main() => print('Hello, world!');");
     expect(unit.toString(), equals("void main() => print('Hello, world!');"));
   });
@@ -24,9 +25,11 @@ void main() {
 
     test('with errors suppressed', () {
       checkCompilationUnit(
+          // ignore: deprecated_member_use_from_same_package
           parseCompilationUnit(contents, suppressErrors: true));
     });
     test('with errors enabled', () {
+      // ignore: deprecated_member_use_from_same_package
       checkCompilationUnit(parseCompilationUnit(contents));
     });
   });
@@ -45,15 +48,18 @@ void main() {
 
     test('with errors suppressed', () {
       checkCompilationUnit(
+          // ignore: deprecated_member_use_from_same_package
           parseCompilationUnit(contents, suppressErrors: true));
     });
     test('with errors enabled', () {
+      // ignore: deprecated_member_use_from_same_package
       checkCompilationUnit(parseCompilationUnit(contents));
     });
   });
 
   test("throws errors for an invalid compilation unit", () {
     expect(() {
+      // ignore: deprecated_member_use_from_same_package
       parseCompilationUnit("void main() => print('Hello, world!')",
           name: 'test.dart');
     }, throwsA(predicate((error) {
@@ -64,6 +70,7 @@ void main() {
 
   test("defaults to '<unknown source>' if no name is provided", () {
     expect(() {
+      // ignore: deprecated_member_use_from_same_package
       parseCompilationUnit("void main() => print('Hello, world!')");
     }, throwsA(predicate((error) {
       return error is AnalyzerErrorGroup &&
@@ -74,12 +81,14 @@ void main() {
   });
 
   test("allows you to specify whether or not to parse function bodies", () {
+    // ignore: deprecated_member_use_from_same_package
     var unit = parseCompilationUnit("void main() => print('Hello, world!');",
         parseFunctionBodies: false);
     expect(unit.toString(), equals("void main();"));
   });
 
   test("allows you to specify whether or not to parse function bodies 2", () {
+    // ignore: deprecated_member_use_from_same_package
     var unit = parseCompilationUnit("void main() { print('Hello, world!'); }",
         parseFunctionBodies: false);
     expect(unit.toString(), equals("void main();"));

pkg/dev_compiler/tool/patch_sdk.dart

@@ -9,9 +9,7 @@
 import 'dart:io';
 import 'dart:math' as math;
 
-// ignore: deprecated_member_use
+import 'package:analyzer/dart/analysis/utilities.dart';
-import 'package:analyzer/analyzer.dart'
-    show parseCompilationUnit, parseDirectives;
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/ast/token.dart';
 import 'package:analyzer/dart/ast/visitor.dart';
@@ -90,7 +88,7 @@ void main(List<String> argv) {
       int inputModifyTime = math.max(selfModifyTime,
           libraryFile.lastModifiedSync().millisecondsSinceEpoch);
       var partFiles = <File>[];
-      for (var part in parseDirectives(libraryContents).directives) {
+      for (var part in parseString(content: libraryContents).unit.directives) {
         if (part is PartDirective) {
           var partPath = part.uri.stringValue;
           outPaths.add(path.join(path.dirname(libraryOut), partPath));
@@ -188,7 +186,7 @@ List<String> _patchLibrary(List<String> partsContents, String patchContents) {
   bool failed = false;
   for (var partContent in partsContents) {
     var partEdits = StringEditBuffer(partContent);
-    var partUnit = parseCompilationUnit(partContent);
+    var partUnit = parseString(content: partContent).unit;
     var patcher = PatchApplier(partEdits, patchFinder);
     partUnit.accept(patcher);
     if (!failed) failed = patcher.patchWasMissing;
@@ -315,7 +313,7 @@ class PatchFinder extends GeneralizingAstVisitor {
 
   PatchFinder.parseAndVisit(String contents)
       : contents = contents,
-        unit = parseCompilationUnit(contents) {
+        unit = parseString(content: contents).unit {
     visitCompilationUnit(unit);
   }
 
@@ -482,6 +480,6 @@ List<SdkLibrary> _getSdkLibraries(String contents) {
   // It doesn't understand optional new/const in Dart 2. For now, we keep
   // redundant `const` in tool/input_sdk/libraries.dart as a workaround.
   var libraryBuilder = SdkLibrariesReader_LibraryBuilder(true);
-  parseCompilationUnit(contents).accept(libraryBuilder);
+  parseString(content: contents).unit.accept(libraryBuilder);
   return libraryBuilder.librariesMap.sdkLibraries;
 }