From 16cb7cee1ba74da8caa17594766e8ffcd42e2a75 Mon Sep 17 00:00:00 2001 From: Paul Berry Date: Tue, 21 Jan 2020 15:58:02 +0000 Subject: [PATCH] Convert builder.dart to triple-slash comment style Change-Id: I73e371b073ef2f7448a175b5fdb85bd77d8529a6 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/132460 Reviewed-by: Brian Wilkerson --- pkg/analyzer/lib/src/context/builder.dart | 342 ++++++++-------------- 1 file changed, 126 insertions(+), 216 deletions(-) diff --git a/pkg/analyzer/lib/src/context/builder.dart b/pkg/analyzer/lib/src/context/builder.dart index 5a6120795a4..c6e34fb94b5 100644 --- a/pkg/analyzer/lib/src/context/builder.dart +++ b/pkg/analyzer/lib/src/context/builder.dart @@ -44,97 +44,71 @@ import 'package:args/args.dart'; import 'package:path/src/context.dart'; import 'package:yaml/yaml.dart'; -/** - * A utility class used to build an analysis context for a given directory. - * - * The construction of analysis contexts is as follows: - * - * 1. Determine how package: URI's are to be resolved. This follows the lookup - * algorithm defined by the [package specification][1]. - * - * 2. Using the results of step 1, look in each package for an embedder file - * (_embedder.yaml). If one exists then it defines the SDK. If multiple such - * files exist then use the first one found. Otherwise, use the default SDK. - * - * 3. Look for an analysis options file (`analysis_options.yaml` or - * `.analysis_options`) and process the options in the file. - * - * 4. Create a new context. Initialize its source factory based on steps 1, 2 - * and 3. Initialize its analysis options from step 4. - * - * [1]: https://github.com/dart-lang/dart_enhancement_proposals/blob/master/Accepted/0005%20-%20Package%20Specification/DEP-pkgspec.md. - */ +/// A utility class used to build an analysis context for a given directory. +/// +/// The construction of analysis contexts is as follows: +/// +/// 1. Determine how package: URI's are to be resolved. This follows the lookup +/// algorithm defined by the [package specification][1]. +/// +/// 2. Using the results of step 1, look in each package for an embedder file +/// (_embedder.yaml). If one exists then it defines the SDK. If multiple such +/// files exist then use the first one found. Otherwise, use the default SDK. +/// +/// 3. Look for an analysis options file (`analysis_options.yaml` or +/// `.analysis_options`) and process the options in the file. +/// +/// 4. Create a new context. Initialize its source factory based on steps 1, 2 +/// and 3. Initialize its analysis options from step 4. +/// +/// [1]: https://github.com/dart-lang/dart_enhancement_proposals/blob/master/Accepted/0005%20-%20Package%20Specification/DEP-pkgspec.md. class ContextBuilder { - /** - * A callback for when analysis drivers are created, which takes all the same - * arguments as the dart analysis driver constructor so that plugins may - * create their own drivers with the same tools, in theory. Here as a stopgap - * until the official plugin API is complete - */ + /// A callback for when analysis drivers are created, which takes all the same + /// arguments as the dart analysis driver constructor so that plugins may + /// create their own drivers with the same tools, in theory. Here as a stopgap + /// until the official plugin API is complete static Function onCreateAnalysisDriver; - /** - * The [ResourceProvider] by which paths are converted into [Resource]s. - */ + /// The [ResourceProvider] by which paths are converted into [Resource]s. final ResourceProvider resourceProvider; - /** - * The manager used to manage the DartSdk's that have been created so that - * they can be shared across contexts. - */ + /// The manager used to manage the DartSdk's that have been created so that + /// they can be shared across contexts. final DartSdkManager sdkManager; - /** - * The cache containing the contents of overlaid files. If this builder will - * be used to build analysis drivers, set the [fileContentOverlay] instead. - */ + /// The cache containing the contents of overlaid files. If this builder will + /// be used to build analysis drivers, set the [fileContentOverlay] instead. final ContentCache contentCache; - /** - * The options used by the context builder. - */ + /// The options used by the context builder. final ContextBuilderOptions builderOptions; - /** - * The scheduler used by any analysis drivers created through this interface. - */ + /// The scheduler used by any analysis drivers created through this interface. AnalysisDriverScheduler analysisDriverScheduler; - /** - * The performance log used by any analysis drivers created through this - * interface. - */ + /// The performance log used by any analysis drivers created through this + /// interface. PerformanceLog performanceLog; - /** - * The byte store used by any analysis drivers created through this interface. - */ + /// The byte store used by any analysis drivers created through this interface. ByteStore byteStore; - /** - * The file content overlay used by analysis drivers. If this builder will be - * used to build analysis contexts, set the [contentCache] instead. - */ + /// The file content overlay used by analysis drivers. If this builder will be + /// used to build analysis contexts, set the [contentCache] instead. FileContentOverlay fileContentOverlay; - /** - * Whether any analysis driver created through this interface should support - * indexing and search. - */ + /// Whether any analysis driver created through this interface should support + /// indexing and search. bool enableIndex = false; - /** - * Initialize a newly created builder to be ready to build a context rooted in - * the directory with the given [rootDirectoryPath]. - */ + /// Initialize a newly created builder to be ready to build a context rooted in + /// the directory with the given [rootDirectoryPath]. ContextBuilder(this.resourceProvider, this.sdkManager, this.contentCache, {ContextBuilderOptions options}) : builderOptions = options ?? ContextBuilderOptions(); - /** - * Return an analysis driver that is configured correctly to analyze code in - * the directory with the given [path]. - */ + /// Return an analysis driver that is configured correctly to analyze code in + /// the directory with the given [path]. AnalysisDriver buildDriver(ContextRoot contextRoot) { String path = contextRoot.root; AnalysisOptions options = @@ -180,9 +154,7 @@ class ContextBuilder { return driver; } - /** - * Return an analysis options object containing the default option values. - */ + /// Return an analysis options object containing the default option values. AnalysisOptions createDefaultOptions() { AnalysisOptions defaultOptions = builderOptions.defaultOptions; if (defaultOptions == null) { @@ -239,10 +211,8 @@ class ContextBuilder { return workspace.createSourceFactory(sdk, summaryData); } - /** - * Add any [declaredVariables] to the list of declared variables used by the - * given analysis [driver]. - */ + /// Add any [declaredVariables] to the list of declared variables used by the + /// given analysis [driver]. void declareVariablesInDriver(AnalysisDriver driver) { Map variables = builderOptions.declaredVariables; if (variables != null && variables.isNotEmpty) { @@ -251,16 +221,14 @@ class ContextBuilder { } } - /** - * Finds a package resolution strategy for the directory at the given absolute - * [path]. - * - * This function first tries to locate a `.packages` file in the directory. If - * that is not found, it instead checks for the presence of a `packages/` - * directory in the same place. If that also fails, it starts checking parent - * directories for a `.packages` file, and stops if it finds it. Otherwise it - * gives up and returns [Packages.empty]. - */ + /// Finds a package resolution strategy for the directory at the given absolute + /// [path]. + /// + /// This function first tries to locate a `.packages` file in the directory. If + /// that is not found, it instead checks for the presence of a `packages/` + /// directory in the same place. If that also fails, it starts checking parent + /// directories for a `.packages` file, and stops if it finds it. Otherwise it + /// gives up and returns [Packages.empty]. Packages findPackagesFromFile(String path) { Resource location = _findPackagesLocation(path); if (location is File) { @@ -275,12 +243,10 @@ class ContextBuilder { return Packages.empty; } - /** - * Return the SDK that should be used to analyze code. Use the given - * [workspace] and [analysisOptions] to locate the SDK. - * - * TODO(scheglov) Remove [analysisOptions]? - */ + /// Return the SDK that should be used to analyze code. Use the given + /// [workspace] and [analysisOptions] to locate the SDK. + /// + /// TODO(scheglov) Remove [analysisOptions]? DartSdk findSdk(Workspace workspace, AnalysisOptions analysisOptions) { String summaryPath = builderOptions.dartSdkSummaryPath; if (summaryPath != null) { @@ -399,14 +365,12 @@ class ContextBuilder { return options; } - /** - * Return the analysis options file that should be used when analyzing code in - * the directory with the given [path]. - * - * If [forceSearch] is true, then don't return the default analysis options - * path. This allows cli to locate what *would* have been the analysis options - * file path, and super-impose the defaults over it in-place. - */ + /// Return the analysis options file that should be used when analyzing code in + /// the directory with the given [path]. + /// + /// If [forceSearch] is true, then don't return the default analysis options + /// path. This allows cli to locate what *would* have been the analysis options + /// file path, and super-impose the defaults over it in-place. File getOptionsFile(String path, {bool forceSearch = false}) { if (!forceSearch) { String filePath = builderOptions.defaultAnalysisOptionsFilePath; @@ -430,14 +394,12 @@ class ContextBuilder { return null; } - /** - * Create a [Packages] object for a 'package' directory ([folder]). - * - * Package names are resolved as relative to sub-directories of the package - * directory. - * - * TODO(scheglov) Remove this feature - */ + /// Create a [Packages] object for a 'package' directory ([folder]). + /// + /// Package names are resolved as relative to sub-directories of the package + /// directory. + /// + /// TODO(scheglov) Remove this feature Packages getPackagesFromFolder(Folder folder) { Context pathContext = resourceProvider.pathContext; var map = {}; @@ -460,9 +422,7 @@ class ContextBuilder { return Packages(map); } - /** - * Resolve any symbolic links encoded in the path to the given [folder]. - */ + /// Resolve any symbolic links encoded in the path to the given [folder]. String resolveSymbolicLink(Folder folder) { try { return folder.resolveSymbolicLinksSync().path; @@ -471,10 +431,8 @@ class ContextBuilder { } } - /** - * Resolve any symbolic links encoded in the URI's in the given [map] by - * replacing the values in the map. - */ + /// Resolve any symbolic links encoded in the URI's in the given [map] by + /// replacing the values in the map. void resolveSymbolicLinks(Map map) { Context pathContext = resourceProvider.pathContext; for (String packageName in map.keys) { @@ -489,19 +447,17 @@ class ContextBuilder { } } - /** - * Find the location of the package resolution file/directory for the - * directory at the given absolute [path]. - * - * Checks for a `.packages` file in the [path]. If not found, - * checks for a `packages` directory in the same directory. If still not - * found, starts checking parent directories for `.packages` until reaching - * the root directory. - * - * Return a [File] object representing a `.packages` file if one is found, a - * [Folder] object for the `packages/` directory if that is found, or `null` - * if neither is found. - */ + /// Find the location of the package resolution file/directory for the + /// directory at the given absolute [path]. + /// + /// Checks for a `.packages` file in the [path]. If not found, + /// checks for a `packages` directory in the same directory. If still not + /// found, starts checking parent directories for `.packages` until reaching + /// the root directory. + /// + /// Return a [File] object representing a `.packages` file if one is found, a + /// [Folder] object for the `packages/` directory if that is found, or `null` + /// if neither is found. Resource _findPackagesLocation(String path) { var resource = resourceProvider.getResource(path); while (resource != null) { @@ -521,10 +477,8 @@ class ContextBuilder { return null; } - /** - * Return the `pubspec.yaml` file that should be used when analyzing code in - * the directory with the given [path], possibly `null`. - */ + /// Return the `pubspec.yaml` file that should be used when analyzing code in + /// the directory with the given [path], possibly `null`. File _findPubspecFile(String path) { var resource = resourceProvider.getResource(path); while (resource != null) { @@ -565,10 +519,8 @@ class ContextBuilder { return workspace; } - /** - * Return `true` if either the directory at [rootPath] or a parent of that - * directory contains a `.packages` file. - */ + /// Return `true` if either the directory at [rootPath] or a parent of that + /// directory contains a `.packages` file. static bool _hasPackageFileInPath( ResourceProvider resourceProvider, String rootPath) { Folder folder = resourceProvider.getFolder(rootPath); @@ -583,113 +535,79 @@ class ContextBuilder { } } -/** - * Options used by a [ContextBuilder]. - */ +/// Options used by a [ContextBuilder]. class ContextBuilderOptions { - /** - * The results of parsing the command line arguments as defined by - * [defineAnalysisArguments] or `null` if none. - */ + /// The results of parsing the command line arguments as defined by + /// [defineAnalysisArguments] or `null` if none. ArgResults argResults; - /** - * The file path of the file containing the summary of the SDK that should be - * used to "analyze" the SDK. This option should only be specified by - * command-line tools such as 'dartanalyzer' or 'ddc'. - */ + /// The file path of the file containing the summary of the SDK that should be + /// used to "analyze" the SDK. This option should only be specified by + /// command-line tools such as 'dartanalyzer' or 'ddc'. String dartSdkSummaryPath; - /** - * The file path of the analysis options file that should be used in place of - * any file in the root directory or a parent of the root directory, or `null` - * if the normal lookup mechanism should be used. - */ + /// The file path of the analysis options file that should be used in place of + /// any file in the root directory or a parent of the root directory, or `null` + /// if the normal lookup mechanism should be used. String defaultAnalysisOptionsFilePath; - /** - * A table mapping variable names to values for the declared variables, or - * `null` if no additional variables should be declared. - */ + /// A table mapping variable names to values for the declared variables, or + /// `null` if no additional variables should be declared. Map declaredVariables; - /** - * The default analysis options that should be used unless some or all of them - * are overridden in the analysis options file, or `null` if the default - * defaults should be used. - */ + /// The default analysis options that should be used unless some or all of them + /// are overridden in the analysis options file, or `null` if the default + /// defaults should be used. AnalysisOptions defaultOptions; - /** - * The file path of the .packages file that should be used in place of any - * file found using the normal (Package Specification DEP) lookup mechanism, - * or `null` if the normal lookup mechanism should be used. - */ + /// The file path of the .packages file that should be used in place of any + /// file found using the normal (Package Specification DEP) lookup mechanism, + /// or `null` if the normal lookup mechanism should be used. String defaultPackageFilePath; - /** - * The file path of the packages directory that should be used in place of any - * file found using the normal (Package Specification DEP) lookup mechanism, - * or `null` if the normal lookup mechanism should be used. - */ + /// The file path of the packages directory that should be used in place of any + /// file found using the normal (Package Specification DEP) lookup mechanism, + /// or `null` if the normal lookup mechanism should be used. String defaultPackagesDirectoryPath; - /** - * A list of the paths of summary files that are to be used, or `null` if no - * summary information is available. - */ + /// A list of the paths of summary files that are to be used, or `null` if no + /// summary information is available. List librarySummaryPaths; - /** - * Initialize a newly created set of options - */ + /// Initialize a newly created set of options ContextBuilderOptions(); } -/** - * Given a package map, check in each package's lib directory for the existence - * of an `_embedder.yaml` file. If the file contains a top level YamlMap, it - * will be added to the [embedderYamls] map. - */ +/// Given a package map, check in each package's lib directory for the existence +/// of an `_embedder.yaml` file. If the file contains a top level YamlMap, it +/// will be added to the [embedderYamls] map. class EmbedderYamlLocator { - /** - * The name of the embedder files being searched for. - */ + /// The name of the embedder files being searched for. static const String EMBEDDER_FILE_NAME = '_embedder.yaml'; - /** - * A mapping from a package's library directory to the parsed YamlMap. - */ + /// A mapping from a package's library directory to the parsed YamlMap. final Map embedderYamls = HashMap(); - /** - * Initialize a newly created locator by processing the packages in the given - * [packageMap]. - */ + /// Initialize a newly created locator by processing the packages in the given + /// [packageMap]. EmbedderYamlLocator(Map> packageMap) { if (packageMap != null) { _processPackageMap(packageMap); } } - /** - * Initialize with the given [libFolder] of `sky_engine` package. - */ + /// Initialize with the given [libFolder] of `sky_engine` package. EmbedderYamlLocator.forLibFolder(Folder libFolder) { _processPackage([libFolder]); } - /** - * Programmatically add an `_embedder.yaml` mapping. - */ + /// Programmatically add an `_embedder.yaml` mapping. void addEmbedderYaml(Folder libDir, String embedderYaml) { _processEmbedderYaml(libDir, embedderYaml); } - /** - * Refresh the map of located files to those found by processing the given - * [packageMap]. - */ + /// Refresh the map of located files to those found by processing the given + /// [packageMap]. void refresh(Map> packageMap) { // Clear existing. embedderYamls.clear(); @@ -698,10 +616,8 @@ class EmbedderYamlLocator { } } - /** - * Given the yaml for an embedder ([embedderYaml]) and a folder ([libDir]), - * setup the uri mapping. - */ + /// Given the yaml for an embedder ([embedderYaml]) and a folder ([libDir]), + /// setup the uri mapping. void _processEmbedderYaml(Folder libDir, String embedderYaml) { try { YamlNode yaml = loadYaml(embedderYaml); @@ -713,10 +629,8 @@ class EmbedderYamlLocator { } } - /** - * Given a package list of folders ([libDirs]), process any - * `_embedder.yaml` files that are found in any of the folders. - */ + /// Given a package list of folders ([libDirs]), process any + /// `_embedder.yaml` files that are found in any of the folders. void _processPackage(List libDirs) { for (Folder libDir in libDirs) { String embedderYaml = _readEmbedderYaml(libDir); @@ -726,17 +640,13 @@ class EmbedderYamlLocator { } } - /** - * Process each of the entries in the [packageMap]. - */ + /// Process each of the entries in the [packageMap]. void _processPackageMap(Map> packageMap) { packageMap.values.forEach(_processPackage); } - /** - * Read and return the contents of [libDir]/[EMBEDDER_FILE_NAME], or `null` if - * the file doesn't exist. - */ + /// Read and return the contents of [libDir]/[EMBEDDER_FILE_NAME], or `null` if + /// the file doesn't exist. String _readEmbedderYaml(Folder libDir) { File file = libDir.getChild(EMBEDDER_FILE_NAME); try {