Skip to content

Commit a89b7a4

Browse files
srawlinscommit-bot@chromium.org
authored andcommitted
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>
1 parent 66c1b51 commit a89b7a4

40 files changed

+1366
-2523
lines changed

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

Lines changed: 16 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -4,34 +4,26 @@
44

55
import 'cache.dart';
66

7-
/**
8-
* Store of bytes associated with string keys.
9-
*
10-
* Each key must be not longer than 100 characters and consist of only `[a-z]`,
11-
* `[0-9]`, `.` and `_` characters. The key cannot be an empty string, the
12-
* literal `.`, or contain the sequence `..`.
13-
*
14-
* Note that associations are not guaranteed to be persistent. The value
15-
* associated with a key can change or become `null` at any point in time.
16-
*
17-
* TODO(scheglov) Research using asynchronous API.
18-
*/
7+
/// Store of bytes associated with string keys.
8+
///
9+
/// Each key must be not longer than 100 characters and consist of only `[a-z]`,
10+
/// `[0-9]`, `.` and `_` characters. The key cannot be an empty string, the
11+
/// literal `.`, or contain the sequence `..`.
12+
///
13+
/// Note that associations are not guaranteed to be persistent. The value
14+
/// associated with a key can change or become `null` at any point in time.
15+
///
16+
/// TODO(scheglov) Research using asynchronous API.
1917
abstract class ByteStore {
20-
/**
21-
* Return the bytes associated with the given [key].
22-
* Return `null` if the association does not exist.
23-
*/
18+
/// Return the bytes associated with the given [key].
19+
/// Return `null` if the association does not exist.
2420
List<int> get(String key);
2521

26-
/**
27-
* Associate the given [bytes] with the [key].
28-
*/
22+
/// Associate the given [bytes] with the [key].
2923
void put(String key, List<int> bytes);
3024
}
3125

32-
/**
33-
* [ByteStore] which stores data only in memory.
34-
*/
26+
/// [ByteStore] which stores data only in memory.
3527
class MemoryByteStore implements ByteStore {
3628
final Map<String, List<int>> _map = {};
3729

@@ -46,9 +38,7 @@ class MemoryByteStore implements ByteStore {
4638
}
4739
}
4840

49-
/**
50-
* A wrapper around [ByteStore] which adds an in-memory LRU cache to it.
51-
*/
41+
/// A wrapper around [ByteStore] which adds an in-memory LRU cache to it.
5242
class MemoryCachingByteStore implements ByteStore {
5343
final ByteStore _store;
5444
final Cache<String, List<int>> _cache;
@@ -68,9 +58,7 @@ class MemoryCachingByteStore implements ByteStore {
6858
}
6959
}
7060

71-
/**
72-
* [ByteStore] which does not store any data.
73-
*/
61+
/// [ByteStore] which does not store any data.
7462
class NullByteStore implements ByteStore {
7563
@override
7664
List<int> get(String key) => null;

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

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5-
/**
6-
* LRU cache of objects.
7-
*/
5+
/// LRU cache of objects.
86
class Cache<K, V> {
97
final int _maxSizeBytes;
108
final int Function(V) _meter;

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

Lines changed: 9 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -25,28 +25,20 @@ import 'package:analyzer/src/generated/sdk.dart' show DartSdkManager;
2525
import 'package:analyzer/src/generated/source.dart' show ContentCache;
2626
import 'package:meta/meta.dart';
2727

28-
/**
29-
* An implementation of a context builder.
30-
*/
28+
/// An implementation of a context builder.
3129
class ContextBuilderImpl implements ContextBuilder {
32-
/**
33-
* The resource provider used to access the file system.
34-
*/
30+
/// The resource provider used to access the file system.
3531
final ResourceProvider resourceProvider;
3632

37-
/**
38-
* Initialize a newly created context builder. If a [resourceProvider] is
39-
* given, then it will be used to access the file system, otherwise the
40-
* default resource provider will be used.
41-
*/
33+
/// Initialize a newly created context builder. If a [resourceProvider] is
34+
/// given, then it will be used to access the file system, otherwise the
35+
/// default resource provider will be used.
4236
ContextBuilderImpl({ResourceProvider resourceProvider})
4337
: resourceProvider =
4438
resourceProvider ?? PhysicalResourceProvider.INSTANCE;
4539

46-
/**
47-
* Return the path to the default location of the SDK, or `null` if the sdk
48-
* cannot be found.
49-
*/
40+
/// Return the path to the default location of the SDK, or `null` if the sdk
41+
/// cannot be found.
5042
String get _defaultSdkPath =>
5143
FolderBasedDartSdk.defaultSdkDirectory(resourceProvider)?.path;
5244

@@ -113,10 +105,8 @@ class ContextBuilderImpl implements ContextBuilder {
113105
return context;
114106
}
115107

116-
/**
117-
* Convert the [declaredVariables] into a map for use with the old context
118-
* builder.
119-
*/
108+
/// Convert the [declaredVariables] into a map for use with the old context
109+
/// builder.
120110
Map<String, String> _toMap(DeclaredVariables declaredVariables) {
121111
Map<String, String> map = <String, String>{};
122112
for (String name in declaredVariables.variableNames) {

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

Lines changed: 46 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -32,37 +32,25 @@ import 'package:meta/meta.dart';
3232
import 'package:path/path.dart';
3333
import 'package:yaml/yaml.dart';
3434

35-
/**
36-
* An implementation of a context locator.
37-
*/
35+
/// An implementation of a context locator.
3836
class ContextLocatorImpl implements ContextLocator {
39-
/**
40-
* The name of the analysis options file.
41-
*/
37+
/// The name of the analysis options file.
4238
static const String ANALYSIS_OPTIONS_NAME = 'analysis_options.yaml';
4339

44-
/**
45-
* The name of the packages file.
46-
*/
40+
/// The name of the packages file.
4741
static const String PACKAGES_FILE_NAME = '.packages';
4842

49-
/**
50-
* The resource provider used to access the file system.
51-
*/
43+
/// The resource provider used to access the file system.
5244
final ResourceProvider resourceProvider;
5345

54-
/**
55-
* Initialize a newly created context locator. If a [resourceProvider] is
56-
* supplied, it will be used to access the file system. Otherwise the default
57-
* resource provider will be used.
58-
*/
46+
/// Initialize a newly created context locator. If a [resourceProvider] is
47+
/// supplied, it will be used to access the file system. Otherwise the default
48+
/// resource provider will be used.
5949
ContextLocatorImpl({ResourceProvider resourceProvider})
6050
: this.resourceProvider =
6151
resourceProvider ?? PhysicalResourceProvider.INSTANCE;
6252

63-
/**
64-
* Return the path to the default location of the SDK.
65-
*/
53+
/// Return the path to the default location of the SDK.
6654
String get _defaultSdkPath =>
6755
FolderBasedDartSdk.defaultSdkDirectory(resourceProvider).path;
6856

@@ -189,26 +177,23 @@ class ContextLocatorImpl implements ContextLocator {
189177
return roots;
190178
}
191179

192-
/**
193-
* Return `true` if the given [resource] is contained in one or more of the
194-
* given [folders].
195-
*/
180+
/// Return `true` if the given [resource] is contained in one or more of the
181+
/// given [folders].
196182
bool _containedInAny(Iterable<Folder> folders, Resource resource) =>
197183
folders.any((Folder folder) => folder.contains(resource.path));
198184

199-
/**
200-
* If the given [folder] should be the root of a new analysis context, then
201-
* create a new context root for it and add it to the list of context [roots].
202-
* The [containingRoot] is the context root from an enclosing directory and is
203-
* used to inherit configuration information that isn't overridden.
204-
*
205-
* If either the [optionsFile] or [packagesFile] is non-`null` then the given
206-
* file will be used even if there is a local version of the file.
207-
*
208-
* For each directory within the given [folder] that is neither in the list of
209-
* [excludedFolders] nor excluded by the [excludedFilePatterns], recursively
210-
* search for nested context roots.
211-
*/
185+
/// If the given [folder] should be the root of a new analysis context, then
186+
/// create a new context root for it and add it to the list of context
187+
/// [roots]. The [containingRoot] is the context root from an enclosing
188+
/// directory and is used to inherit configuration information that isn't
189+
/// overridden.
190+
///
191+
/// If either the [optionsFile] or [packagesFile] is non-`null` then the given
192+
/// file will be used even if there is a local version of the file.
193+
///
194+
/// For each directory within the given [folder] that is neither in the list
195+
/// of [excludedFolders] nor excluded by the [excludedFilePatterns],
196+
/// recursively search for nested context roots.
212197
void _createContextRoots(
213198
List<ContextRoot> roots,
214199
Folder folder,
@@ -253,14 +238,13 @@ class ContextLocatorImpl implements ContextLocator {
253238
excludedFilePatterns, optionsFile, packagesFile);
254239
}
255240

256-
/**
257-
* For each directory within the given [folder] that is neither in the list of
258-
* [excludedFolders] nor excluded by the [excludedFilePatterns], recursively
259-
* search for nested context roots and add them to the list of [roots].
260-
*
261-
* If either the [optionsFile] or [packagesFile] is non-`null` then the given
262-
* file will be used even if there is a local version of the file.
263-
*/
241+
/// For each directory within the given [folder] that is neither in the list
242+
/// of [excludedFolders] nor excluded by the [excludedFilePatterns],
243+
/// recursively search for nested context roots and add them to the list of
244+
/// [roots].
245+
///
246+
/// If either the [optionsFile] or [packagesFile] is non-`null` then the given
247+
/// file will be used even if there is a local version of the file.
264248
void _createContextRootsIn(
265249
List<ContextRoot> roots,
266250
Folder folder,
@@ -303,11 +287,9 @@ class ContextLocatorImpl implements ContextLocator {
303287
}
304288
}
305289

306-
/**
307-
* Return the analysis options file to be used to analyze files in the given
308-
* [folder], or `null` if there is no analysis options file in the given
309-
* folder or any parent folder.
310-
*/
290+
/// Return the analysis options file to be used to analyze files in the given
291+
/// [folder], or `null` if there is no analysis options file in the given
292+
/// folder or any parent folder.
311293
File _findOptionsFile(Folder folder) {
312294
while (folder != null) {
313295
File packagesFile = _getOptionsFile(folder);
@@ -319,11 +301,9 @@ class ContextLocatorImpl implements ContextLocator {
319301
return null;
320302
}
321303

322-
/**
323-
* Return the packages file to be used to analyze files in the given [folder],
324-
* or `null` if there is no packages file in the given folder or any parent
325-
* folder.
326-
*/
304+
/// Return the packages file to be used to analyze files in the given
305+
/// [folder], or `null` if there is no packages file in the given folder or
306+
/// any parent folder.
327307
File _findPackagesFile(Folder folder) {
328308
while (folder != null) {
329309
File packagesFile = _getPackagesFile(folder);
@@ -375,10 +355,8 @@ class ContextLocatorImpl implements ContextLocator {
375355
return patterns;
376356
}
377357

378-
/**
379-
* If the given [directory] contains a file with the given [name], then return
380-
* the file. Otherwise, return `null`.
381-
*/
358+
/// If the given [directory] contains a file with the given [name], then
359+
/// return the file. Otherwise, return `null`.
382360
File _getFile(Folder directory, String name) {
383361
Resource resource = directory.getChild(name);
384362
if (resource is File && resource.exists) {
@@ -387,24 +365,18 @@ class ContextLocatorImpl implements ContextLocator {
387365
return null;
388366
}
389367

390-
/**
391-
* Return the analysis options file in the given [folder], or `null` if the
392-
* folder does not contain an analysis options file.
393-
*/
368+
/// Return the analysis options file in the given [folder], or `null` if the
369+
/// folder does not contain an analysis options file.
394370
File _getOptionsFile(Folder folder) =>
395371
_getFile(folder, ANALYSIS_OPTIONS_NAME);
396372

397-
/**
398-
* Return the packages file in the given [folder], or `null` if the folder
399-
* does not contain a packages file.
400-
*/
373+
/// Return the packages file in the given [folder], or `null` if the folder
374+
/// does not contain a packages file.
401375
File _getPackagesFile(Folder folder) => _getFile(folder, PACKAGES_FILE_NAME);
402376

403-
/**
404-
* Add to the given lists of [folders] and [files] all of the resources in the
405-
* given list of [paths] that exist and are not contained within one of the
406-
* folders.
407-
*/
377+
/// Add to the given lists of [folders] and [files] all of the resources in
378+
/// the given list of [paths] that exist and are not contained within one of
379+
/// the folders.
408380
void _resourcesFromPaths(
409381
List<String> paths, List<Folder> folders, List<File> files) {
410382
for (String path in _uniqueSortedPaths(paths)) {
@@ -421,10 +393,8 @@ class ContextLocatorImpl implements ContextLocator {
421393
}
422394
}
423395

424-
/**
425-
* Return a list of paths that contains all of the unique elements from the
426-
* given list of [paths], sorted such that shorter paths are first.
427-
*/
396+
/// Return a list of paths that contains all of the unique elements from the
397+
/// given list of [paths], sorted such that shorter paths are first.
428398
List<String> _uniqueSortedPaths(List<String> paths) {
429399
Set<String> uniquePaths = HashSet<String>.from(paths);
430400
List<String> sortedPaths = uniquePaths.toList();

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

Lines changed: 8 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,7 @@ import 'package:analyzer/dart/analysis/context_root.dart';
66
import 'package:analyzer/file_system/file_system.dart';
77
import 'package:path/path.dart';
88

9-
/**
10-
* An implementation of a context root.
11-
*/
9+
/// An implementation of a context root.
1210
class ContextRootImpl implements ContextRoot {
1311
@override
1412
final ResourceProvider resourceProvider;
@@ -28,9 +26,7 @@ class ContextRootImpl implements ContextRoot {
2826
@override
2927
File packagesFile;
3028

31-
/**
32-
* Initialize a newly created context root.
33-
*/
29+
/// Initialize a newly created context root.
3430
ContextRootImpl(this.resourceProvider, this.root);
3531

3632
@override
@@ -71,10 +67,8 @@ class ContextRootImpl implements ContextRoot {
7167
return _isIncluded(path) && !_isExcluded(path);
7268
}
7369

74-
/**
75-
* Return the absolute paths of all of the files that are included in the
76-
* given [folder].
77-
*/
70+
/// Return the absolute paths of all of the files that are included in the
71+
/// given [folder].
7872
Iterable<String> _includedFilesInFolder(Folder folder) sync* {
7973
for (Resource resource in folder.getChildren()) {
8074
String path = resource.path;
@@ -91,10 +85,8 @@ class ContextRootImpl implements ContextRoot {
9185
}
9286
}
9387

94-
/**
95-
* Return `true` if the given [path] is either the same as or inside of one of
96-
* the [excludedPaths].
97-
*/
88+
/// Return `true` if the given [path] is either the same as or inside of one
89+
/// of the [excludedPaths].
9890
bool _isExcluded(String path) {
9991
Context context = resourceProvider.pathContext;
10092
String name = context.basename(path);
@@ -120,10 +112,8 @@ class ContextRootImpl implements ContextRoot {
120112
return false;
121113
}
122114

123-
/**
124-
* Return `true` if the given [path] is either the same as or inside of one of
125-
* the [includedPaths].
126-
*/
115+
/// Return `true` if the given [path] is either the same as or inside of one
116+
/// of the [includedPaths].
127117
bool _isIncluded(String path) {
128118
Context context = resourceProvider.pathContext;
129119
for (String includedPath in includedPaths) {

0 commit comments

Comments
 (0)