analyzer: Improve API of ResourceProviderMixin

Mostly add doc comments, before moving this to public API in the
analyzer_testing package.

* Remove `createResourceProvider`, could be inlined.
* Rename `newBlazeBuildFile` to `newBazelBuildFile`.
* Remove `deleteFile2`; only used once, with an easy replacement.

Change-Id: I296a569b7f68ae9d82e8cb3808931f5590b992cd
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/426903
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
diff --git a/pkg/analysis_server/test/domain_analysis_test.dart b/pkg/analysis_server/test/domain_analysis_test.dart
index 5f041cf..746c44a 100644
--- a/pkg/analysis_server/test/domain_analysis_test.dart
+++ b/pkg/analysis_server/test/domain_analysis_test.dart
@@ -51,7 +51,7 @@
 
   Future<void> test_fileSystem_changeFile_buildFile_legacy() async {
     // Make it a Blaze package.
-    newBlazeBuildFile(myPackageRootPath, r'''
+    newBazelBuildFile(myPackageRootPath, r'''
 # foo
 ''');
 
@@ -70,7 +70,7 @@
 ''');
 
     // Change BUILD file, nothing interesting.
-    newBlazeBuildFile(myPackageRootPath, r'''
+    newBazelBuildFile(myPackageRootPath, r'''
 # bar
 ''');
 
diff --git a/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart b/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart
index e51dc47..75272bb 100644
--- a/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart
+++ b/pkg/analyzer/lib/src/test_utilities/resource_provider_mixin.dart
@@ -9,11 +9,9 @@
 import 'package:analyzer/src/test_utilities/package_config_file_builder.dart';
 import 'package:analyzer/src/util/file_paths.dart' as file_paths;
 import 'package:path/path.dart' as path;
-import 'package:path/path.dart';
 
-/// A mixin for test classes that adds a memory-backed [ResourceProvider] (that
-/// can be overriden via [createResourceProvider]) and utility methods for
-/// manipulating the file system.
+/// A mixin for test classes that adds a memory-backed [ResourceProvider] and
+/// utility methods for manipulating the file system.
 ///
 /// The resource provider will use paths in the same style as the current
 /// platform unless the `TEST_ANALYZER_WINDOWS_PATHS` environment variable is
@@ -22,37 +20,35 @@
 /// The utility methods all take a posix style path and convert it as
 /// appropriate for the actual platform.
 mixin ResourceProviderMixin {
-  late final resourceProvider = createResourceProvider();
+  late final ResourceProvider resourceProvider =
+      Platform.environment['TEST_ANALYZER_WINDOWS_PATHS'] == 'true'
+          ? MemoryResourceProvider(context: path.windows)
+          : MemoryResourceProvider();
 
+  /// The path context of [resourceProvider].
   path.Context get pathContext => resourceProvider.pathContext;
 
+  /// Converts the given posix [filePath] to conform to [resourceProvider]'s
+  /// path context.
   String convertPath(String filePath) => resourceProvider.convertPath(filePath);
 
-  ResourceProvider createResourceProvider() {
-    return Platform.environment['TEST_ANALYZER_WINDOWS_PATHS'] == 'true'
-        ? MemoryResourceProvider(context: path.windows)
-        : MemoryResourceProvider();
-  }
-
+  /// Deletes the analysis options YAML file at [directoryPath].
   void deleteAnalysisOptionsYamlFile(String directoryPath) {
     var path = join(directoryPath, file_paths.analysisOptionsYaml);
     deleteFile(path);
   }
 
+  /// Deletes the file at [path].
   void deleteFile(String path) {
-    String convertedPath = convertPath(path);
-    resourceProvider.getFile(convertedPath).delete();
+    resourceProvider.getFile(convertPath(path)).delete();
   }
 
-  void deleteFile2(File file) {
-    deleteFile(file.path);
-  }
-
+  /// Deletes the folder at [path].
   void deleteFolder(String path) {
-    String convertedPath = convertPath(path);
-    resourceProvider.getFolder(convertedPath).delete();
+    resourceProvider.getFolder(convertPath(path)).delete();
   }
 
+  /// Deletes the `package_config.json` file at [directoryPath].
   void deletePackageConfigJsonFile(String directoryPath) {
     var path = join(
       directoryPath,
@@ -62,20 +58,24 @@
     deleteFile(path);
   }
 
+  /// Returns [uri] as a String.
   String fromUri(Uri uri) {
     return resourceProvider.pathContext.fromUri(uri);
   }
 
+  /// Gets the [File] at [path].
   File getFile(String path) {
     String convertedPath = convertPath(path);
     return resourceProvider.getFile(convertedPath);
   }
 
+  /// Gets the [Folder] at [path].
   Folder getFolder(String path) {
     String convertedPath = convertPath(path);
     return resourceProvider.getFolder(convertedPath);
   }
 
+  /// Joins the part paths as per [path.Context.join].
   String join(
     String part1, [
     String? part2,
@@ -96,46 +96,57 @@
     part8,
   );
 
+  /// Writes [content] to the file at [path].
   void modifyFile(String path, String content) {
     String convertedPath = convertPath(path);
     resourceProvider.getFile(convertedPath).writeAsStringSync(content);
   }
 
+  /// Writes [content] to [file].
   void modifyFile2(File file, String content) {
     modifyFile(file.path, content);
   }
 
+  /// Writes a new `analysis_options.yaml` file at [directoryPath] with
+  /// [content].
   File newAnalysisOptionsYamlFile(String directoryPath, String content) {
     String path = join(directoryPath, file_paths.analysisOptionsYaml);
     return newFile(path, content);
   }
 
-  File newBlazeBuildFile(String directoryPath, String content) {
-    String path = join(directoryPath, file_paths.blazeBuild);
-    return newFile(path, content);
+  /// Creates a new Bazel BUILD file at [directoryPath] with [content].
+  File newBazelBuildFile(String directoryPath, String content) {
+    String filePath = join(directoryPath, file_paths.blazeBuild);
+    return newFile(filePath, content);
   }
 
+  /// Creates a new BUILD.gn file at [directoryPath] with [content].
   File newBuildGnFile(String directoryPath, String content) {
     String path = join(directoryPath, file_paths.buildGn);
     return newFile(path, content);
   }
 
+  /// Writes [content] to the file at [path].
   File newFile(String path, String content) {
     String convertedPath = convertPath(path);
     return resourceProvider.getFile(convertedPath)..writeAsStringSync(content);
   }
 
+  /// Creates and returns a new [Folder] at [path].
   Folder newFolder(String path) {
     String convertedPath = convertPath(path);
     return resourceProvider.getFolder(convertedPath)..create();
   }
 
+  /// Creates and returns a new [Link] at [path] to [target].
   Link newLink(String path, String target) {
     String convertedPath = convertPath(path);
     String convertedTarget = convertPath(target);
     return resourceProvider.getLink(convertedPath)..create(convertedTarget);
   }
 
+  /// Writes a `.dart_tool/package_config.json` file at [directoryPath] with
+  /// [content].
   File newPackageConfigJsonFile(String directoryPath, String content) {
     String path = join(
       directoryPath,
@@ -145,6 +156,7 @@
     return newFile(path, content);
   }
 
+  /// Writes a `.dart_tool/package_config.json` file at [directoryPath].
   File newPackageConfigJsonFileFromBuilder(
     String directoryPath,
     PackageConfigFileBuilder builder,
@@ -153,11 +165,14 @@
     return newPackageConfigJsonFile(directoryPath, content);
   }
 
+  /// Writes a `pubspec.yaml` file at [directoryPath] with [content].
   File newPubspecYamlFile(String directoryPath, String content) {
     String path = join(directoryPath, file_paths.pubspecYaml);
     return newFile(path, content);
   }
 
+  /// Writes a new `.dart_tool/package_config.json` file for a package rooted at
+  /// [packagePath], named [name].
   void newSinglePackageConfigJsonFile({
     required String packagePath,
     required String name,
@@ -167,26 +182,31 @@
     newPackageConfigJsonFileFromBuilder(packagePath, builder);
   }
 
+  /// Converts [path] to a URI.
   Uri toUri(String path) {
     path = convertPath(path);
     return resourceProvider.pathContext.toUri(path);
   }
 
+  /// Converts [path] to a URI and returns the normalized String representation
+  /// of the URI.
   String toUriStr(String path) {
     return toUri(path).toString();
   }
 }
 
 extension ResourceProviderExtensions on ResourceProvider {
-  /// Convert the given posix [path] to conform to this provider's path context.
-  ///
-  /// This is a utility method for testing.
+  /// Converts the given posix [filePath] to conform to this provider's path
+  /// context.
   String convertPath(String filePath) {
-    if (pathContext.style == windows.style) {
-      if (filePath.startsWith(posix.separator)) {
+    if (pathContext.style == path.windows.style) {
+      if (filePath.startsWith(path.posix.separator)) {
         filePath = r'C:' + filePath;
       }
-      filePath = filePath.replaceAll(posix.separator, windows.separator);
+      filePath = filePath.replaceAll(
+        path.posix.separator,
+        path.windows.separator,
+      );
     }
     return filePath;
   }
diff --git a/pkg/analyzer/test/src/dart/analysis/context_locator_test.dart b/pkg/analyzer/test/src/dart/analysis/context_locator_test.dart
index 30d87c7..ecc456e 100644
--- a/pkg/analyzer/test/src/dart/analysis/context_locator_test.dart
+++ b/pkg/analyzer/test/src/dart/analysis/context_locator_test.dart
@@ -333,7 +333,7 @@
   test_locateRoots_multiple_dirAndNestedDir_outerIsBlaze_innerConfigurationFiles() {
     var outerRootFolder = newFolder('/outer');
     newFile('$outerRootFolder/${file_paths.blazeWorkspaceMarker}', '');
-    newBlazeBuildFile('$outerRootFolder', '');
+    newBazelBuildFile('$outerRootFolder', '');
     var innerRootFolder = newFolder('/outer/examples/inner');
     var innerOptionsFile = newAnalysisOptionsYamlFile('$innerRootFolder', '');
     var innerPackagesFile = newPackageConfigJsonFile('$innerRootFolder', '');
@@ -528,8 +528,8 @@
 
     newFile('$workspacePath1/${file_paths.blazeWorkspaceMarker}', '');
     newFile('$workspacePath2/${file_paths.blazeWorkspaceMarker}', '');
-    newBlazeBuildFile(pkgPath1, '');
-    newBlazeBuildFile(pkgPath2, '');
+    newBazelBuildFile(pkgPath1, '');
+    newBazelBuildFile(pkgPath2, '');
 
     var folder1 = newFolder('$pkgPath1/lib/folder1');
     var folder2 = newFolder('$pkgPath2/lib/folder2');
@@ -740,8 +740,8 @@
 
     newFile('$workspacePath1/${file_paths.blazeWorkspaceMarker}', '');
     newFile('$workspacePath2/${file_paths.blazeWorkspaceMarker}', '');
-    newBlazeBuildFile(pkgPath1, '');
-    newBlazeBuildFile(pkgPath2, '');
+    newBazelBuildFile(pkgPath1, '');
+    newBazelBuildFile(pkgPath2, '');
 
     var file1 = newFile('$pkgPath1/lib/file1.dart', '');
     var file2 = newFile('$pkgPath2/lib/file2.dart', '');
@@ -774,8 +774,8 @@
     var barPath = '$workspacePath/bar';
 
     newFile('$workspacePath/${file_paths.blazeWorkspaceMarker}', '');
-    newBlazeBuildFile(fooPath, '');
-    newBlazeBuildFile(barPath, '');
+    newBazelBuildFile(fooPath, '');
+    newBazelBuildFile(barPath, '');
 
     var fooFile = newFile('$fooPath/lib/foo.dart', '');
     var barFile = newFile('$barPath/lib/bar.dart', '');
@@ -1663,7 +1663,7 @@
     var myPackage = getFolder(myPackagePath);
 
     newFile('$workspacePath/${file_paths.blazeWorkspaceMarker}', '');
-    var buildFile = newBlazeBuildFile(myPackagePath, '');
+    var buildFile = newBazelBuildFile(myPackagePath, '');
     var pubspecYamlFile = newPubspecYamlFile(myPackagePath, '');
     var myFile = newFile('$myPackagePath/lib/my.dart', '');
 
diff --git a/pkg/analyzer/test/src/dart/analysis/driver_test.dart b/pkg/analyzer/test/src/dart/analysis/driver_test.dart
index adb735d..624ab7d 100644
--- a/pkg/analyzer/test/src/dart/analysis/driver_test.dart
+++ b/pkg/analyzer/test/src/dart/analysis/driver_test.dart
@@ -4818,7 +4818,7 @@
 ''');
 
     // Remove `a`, so `b` is reanalyzed and has an error.
-    deleteFile2(a);
+    deleteFile(a.path);
     driver.removeFile2(a);
     await assertEventsText(collector, r'''
 [status] working