Use ///-style doc comments in analyzer/lib/src/dart

Bug: #33892
Change-Id: I5c4d112228ab2ee23f59743e005a5fde1ae2fff4
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/152681
Reviewed-by: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>

pkg/analyzer/lib/src/dart/analysis/byte_store.dart

@@ -4,34 +4,26 @@
 
 import 'cache.dart';
 
-/**
- * Store of bytes associated with string keys.
- *
- * Each key must be not longer than 100 characters and consist of only `[a-z]`,
- * `[0-9]`, `.` and `_` characters. The key cannot be an empty string, the
- * literal `.`, or contain the sequence `..`.
- *
- * Note that associations are not guaranteed to be persistent. The value
- * associated with a key can change or become `null` at any point in time.
- *
- * TODO(scheglov) Research using asynchronous API.
- */
+/// Store of bytes associated with string keys.
+///
+/// Each key must be not longer than 100 characters and consist of only `[a-z]`,
+/// `[0-9]`, `.` and `_` characters. The key cannot be an empty string, the
+/// literal `.`, or contain the sequence `..`.
+///
+/// Note that associations are not guaranteed to be persistent. The value
+/// associated with a key can change or become `null` at any point in time.
+///
+/// TODO(scheglov) Research using asynchronous API.
 abstract class ByteStore {
-  /**
-   * Return the bytes associated with the given [key].
-   * Return `null` if the association does not exist.
-   */
+  /// Return the bytes associated with the given [key].
+  /// Return `null` if the association does not exist.
   List<int> get(String key);
 
-  /**
-   * Associate the given [bytes] with the [key].
-   */
+  /// Associate the given [bytes] with the [key].
   void put(String key, List<int> bytes);
 }
 
-/**
- * [ByteStore] which stores data only in memory.
- */
+/// [ByteStore] which stores data only in memory.
 class MemoryByteStore implements ByteStore {
   final Map<String, List<int>> _map = {};
 
@@ -46,9 +38,7 @@ class MemoryByteStore implements ByteStore {
   }
 }
 
-/**
- * A wrapper around [ByteStore] which adds an in-memory LRU cache to it.
- */
+/// A wrapper around [ByteStore] which adds an in-memory LRU cache to it.
 class MemoryCachingByteStore implements ByteStore {
   final ByteStore _store;
   final Cache<String, List<int>> _cache;
@@ -68,9 +58,7 @@ class MemoryCachingByteStore implements ByteStore {
   }
 }
 
-/**
- * [ByteStore] which does not store any data.
- */
+/// [ByteStore] which does not store any data.
 class NullByteStore implements ByteStore {
   @override
   List<int> get(String key) => null;

pkg/analyzer/lib/src/dart/analysis/cache.dart

@@ -2,9 +2,7 @@
 // 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.
 
-/**
- * LRU cache of objects.
- */
+/// LRU cache of objects.
 class Cache<K, V> {
   final int _maxSizeBytes;
   final int Function(V) _meter;

pkg/analyzer/lib/src/dart/analysis/context_builder.dart

@@ -25,28 +25,20 @@ import 'package:analyzer/src/generated/sdk.dart' show DartSdkManager;
 import 'package:analyzer/src/generated/source.dart' show ContentCache;
 import 'package:meta/meta.dart';
 
-/**
- * An implementation of a context builder.
- */
+/// An implementation of a context builder.
 class ContextBuilderImpl implements ContextBuilder {
-  /**
-   * The resource provider used to access the file system.
-   */
+  /// The resource provider used to access the file system.
   final ResourceProvider resourceProvider;
 
-  /**
-   * Initialize a newly created context builder. If a [resourceProvider] is
-   * given, then it will be used to access the file system, otherwise the
-   * default resource provider will be used.
-   */
+  /// Initialize a newly created context builder. If a [resourceProvider] is
+  /// given, then it will be used to access the file system, otherwise the
+  /// default resource provider will be used.
   ContextBuilderImpl({ResourceProvider resourceProvider})
       : resourceProvider =
             resourceProvider ?? PhysicalResourceProvider.INSTANCE;
 
-  /**
-   * Return the path to the default location of the SDK, or `null` if the sdk
-   * cannot be found.
-   */
+  /// Return the path to the default location of the SDK, or `null` if the sdk
+  /// cannot be found.
   String get _defaultSdkPath =>
       FolderBasedDartSdk.defaultSdkDirectory(resourceProvider)?.path;
 
@@ -113,10 +105,8 @@ class ContextBuilderImpl implements ContextBuilder {
     return context;
   }
 
-  /**
-   * Convert the [declaredVariables] into a map for use with the old context
-   * builder.
-   */
+  /// Convert the [declaredVariables] into a map for use with the old context
+  /// builder.
   Map<String, String> _toMap(DeclaredVariables declaredVariables) {
     Map<String, String> map = <String, String>{};
     for (String name in declaredVariables.variableNames) {

pkg/analyzer/lib/src/dart/analysis/context_locator.dart

@@ -32,37 +32,25 @@ import 'package:meta/meta.dart';
 import 'package:path/path.dart';
 import 'package:yaml/yaml.dart';
 
-/**
- * An implementation of a context locator.
- */
+/// An implementation of a context locator.
 class ContextLocatorImpl implements ContextLocator {
-  /**
-   * The name of the analysis options file.
-   */
+  /// The name of the analysis options file.
   static const String ANALYSIS_OPTIONS_NAME = 'analysis_options.yaml';
 
-  /**
-   * The name of the packages file.
-   */
+  /// The name of the packages file.
   static const String PACKAGES_FILE_NAME = '.packages';
 
-  /**
-   * The resource provider used to access the file system.
-   */
+  /// The resource provider used to access the file system.
   final ResourceProvider resourceProvider;
 
-  /**
-   * Initialize a newly created context locator. If a [resourceProvider] is
-   * supplied, it will be used to access the file system. Otherwise the default
-   * resource provider will be used.
-   */
+  /// Initialize a newly created context locator. If a [resourceProvider] is
+  /// supplied, it will be used to access the file system. Otherwise the default
+  /// resource provider will be used.
   ContextLocatorImpl({ResourceProvider resourceProvider})
       : this.resourceProvider =
             resourceProvider ?? PhysicalResourceProvider.INSTANCE;
 
-  /**
-   * Return the path to the default location of the SDK.
-   */
+  /// Return the path to the default location of the SDK.
   String get _defaultSdkPath =>
       FolderBasedDartSdk.defaultSdkDirectory(resourceProvider).path;
 
@@ -189,26 +177,23 @@ class ContextLocatorImpl implements ContextLocator {
     return roots;
   }
 
-  /**
-   * Return `true` if the given [resource] is contained in one or more of the
-   * given [folders].
-   */
+  /// Return `true` if the given [resource] is contained in one or more of the
+  /// given [folders].
   bool _containedInAny(Iterable<Folder> folders, Resource resource) =>
       folders.any((Folder folder) => folder.contains(resource.path));
 
-  /**
-   * If the given [folder] should be the root of a new analysis context, then
-   * create a new context root for it and add it to the list of context [roots].
-   * The [containingRoot] is the context root from an enclosing directory and is
-   * used to inherit configuration information that isn't overridden.
-   *
-   * If either the [optionsFile] or [packagesFile] is non-`null` then the given
-   * file will be used even if there is a local version of the file.
-   *
-   * For each directory within the given [folder] that is neither in the list of
-   * [excludedFolders] nor excluded by the [excludedFilePatterns], recursively
-   * search for nested context roots.
-   */
+  /// If the given [folder] should be the root of a new analysis context, then
+  /// create a new context root for it and add it to the list of context
+  /// [roots]. The [containingRoot] is the context root from an enclosing
+  /// directory and is used to inherit configuration information that isn't
+  /// overridden.
+  ///
+  /// If either the [optionsFile] or [packagesFile] is non-`null` then the given
+  /// file will be used even if there is a local version of the file.
+  ///
+  /// For each directory within the given [folder] that is neither in the list
+  /// of [excludedFolders] nor excluded by the [excludedFilePatterns],
+  /// recursively search for nested context roots.
   void _createContextRoots(
       List<ContextRoot> roots,
       Folder folder,
@@ -253,14 +238,13 @@ class ContextLocatorImpl implements ContextLocator {
         excludedFilePatterns, optionsFile, packagesFile);
   }
 
-  /**
-   * For each directory within the given [folder] that is neither in the list of
-   * [excludedFolders] nor excluded by the [excludedFilePatterns], recursively
-   * search for nested context roots and add them to the list of [roots].
-   *
-   * If either the [optionsFile] or [packagesFile] is non-`null` then the given
-   * file will be used even if there is a local version of the file.
-   */
+  /// For each directory within the given [folder] that is neither in the list
+  /// of [excludedFolders] nor excluded by the [excludedFilePatterns],
+  /// recursively search for nested context roots and add them to the list of
+  /// [roots].
+  ///
+  /// If either the [optionsFile] or [packagesFile] is non-`null` then the given
+  /// file will be used even if there is a local version of the file.
   void _createContextRootsIn(
       List<ContextRoot> roots,
       Folder folder,
@@ -303,11 +287,9 @@ class ContextLocatorImpl implements ContextLocator {
     }
   }
 
-  /**
-   * Return the analysis options file to be used to analyze files in the given
-   * [folder], or `null` if there is no analysis options file in the given
-   * folder or any parent folder.
-   */
+  /// Return the analysis options file to be used to analyze files in the given
+  /// [folder], or `null` if there is no analysis options file in the given
+  /// folder or any parent folder.
   File _findOptionsFile(Folder folder) {
     while (folder != null) {
       File packagesFile = _getOptionsFile(folder);
@@ -319,11 +301,9 @@ class ContextLocatorImpl implements ContextLocator {
     return null;
   }
 
-  /**
-   * Return the packages file to be used to analyze files in the given [folder],
-   * or `null` if there is no packages file in the given folder or any parent
-   * folder.
-   */
+  /// Return the packages file to be used to analyze files in the given
+  /// [folder], or `null` if there is no packages file in the given folder or
+  /// any parent folder.
   File _findPackagesFile(Folder folder) {
     while (folder != null) {
       File packagesFile = _getPackagesFile(folder);
@@ -375,10 +355,8 @@ class ContextLocatorImpl implements ContextLocator {
     return patterns;
   }
 
-  /**
-   * If the given [directory] contains a file with the given [name], then return
-   * the file. Otherwise, return `null`.
-   */
+  /// If the given [directory] contains a file with the given [name], then
+  /// return the file. Otherwise, return `null`.
   File _getFile(Folder directory, String name) {
     Resource resource = directory.getChild(name);
     if (resource is File && resource.exists) {
@@ -387,24 +365,18 @@ class ContextLocatorImpl implements ContextLocator {
     return null;
   }
 
-  /**
-   * Return the analysis options file in the given [folder], or `null` if the
-   * folder does not contain an analysis options file.
-   */
+  /// Return the analysis options file in the given [folder], or `null` if the
+  /// folder does not contain an analysis options file.
   File _getOptionsFile(Folder folder) =>
       _getFile(folder, ANALYSIS_OPTIONS_NAME);
 
-  /**
-   * Return the packages file in the given [folder], or `null` if the folder
-   * does not contain a packages file.
-   */
+  /// Return the packages file in the given [folder], or `null` if the folder
+  /// does not contain a packages file.
   File _getPackagesFile(Folder folder) => _getFile(folder, PACKAGES_FILE_NAME);
 
-  /**
-   * Add to the given lists of [folders] and [files] all of the resources in the
-   * given list of [paths] that exist and are not contained within one of the
-   * folders.
-   */
+  /// Add to the given lists of [folders] and [files] all of the resources in
+  /// the given list of [paths] that exist and are not contained within one of
+  /// the folders.
   void _resourcesFromPaths(
       List<String> paths, List<Folder> folders, List<File> files) {
     for (String path in _uniqueSortedPaths(paths)) {
@@ -421,10 +393,8 @@ class ContextLocatorImpl implements ContextLocator {
     }
   }
 
-  /**
-   * Return a list of paths that contains all of the unique elements from the
-   * given list of [paths], sorted such that shorter paths are first.
-   */
+  /// Return a list of paths that contains all of the unique elements from the
+  /// given list of [paths], sorted such that shorter paths are first.
   List<String> _uniqueSortedPaths(List<String> paths) {
     Set<String> uniquePaths = HashSet<String>.from(paths);
     List<String> sortedPaths = uniquePaths.toList();

pkg/analyzer/lib/src/dart/analysis/context_root.dart

@@ -6,9 +6,7 @@ import 'package:analyzer/dart/analysis/context_root.dart';
 import 'package:analyzer/file_system/file_system.dart';
 import 'package:path/path.dart';
 
-/**
- * An implementation of a context root.
- */
+/// An implementation of a context root.
 class ContextRootImpl implements ContextRoot {
   @override
   final ResourceProvider resourceProvider;
@@ -28,9 +26,7 @@ class ContextRootImpl implements ContextRoot {
   @override
   File packagesFile;
 
-  /**
-   * Initialize a newly created context root.
-   */
+  /// Initialize a newly created context root.
   ContextRootImpl(this.resourceProvider, this.root);
 
   @override
@@ -71,10 +67,8 @@ class ContextRootImpl implements ContextRoot {
     return _isIncluded(path) && !_isExcluded(path);
   }
 
-  /**
-   * Return the absolute paths of all of the files that are included in the
-   * given [folder].
-   */
+  /// Return the absolute paths of all of the files that are included in the
+  /// given [folder].
   Iterable<String> _includedFilesInFolder(Folder folder) sync* {
     for (Resource resource in folder.getChildren()) {
       String path = resource.path;
@@ -91,10 +85,8 @@ class ContextRootImpl implements ContextRoot {
     }
   }
 
-  /**
-   * Return `true` if the given [path] is either the same as or inside of one of
-   * the [excludedPaths].
-   */
+  /// Return `true` if the given [path] is either the same as or inside of one
+  /// of the [excludedPaths].
   bool _isExcluded(String path) {
     Context context = resourceProvider.pathContext;
     String name = context.basename(path);
@@ -120,10 +112,8 @@ class ContextRootImpl implements ContextRoot {
     return false;
   }
 
-  /**
-   * Return `true` if the given [path] is either the same as or inside of one of
-   * the [includedPaths].
-   */
+  /// Return `true` if the given [path] is either the same as or inside of one
+  /// of the [includedPaths].
   bool _isIncluded(String path) {
     Context context = resourceProvider.pathContext;
     for (String includedPath in includedPaths) {