Avoid [this] in Dartdoc comments (#2273)

Dartdoc broke this in dart-lang/dartdoc#3765.
sass · Jul 9, 2024 · 1edc247 · 1edc247
1 parent a164889
commit 1edc247
Show file tree

Hide file tree

Showing 21 changed files with 74 additions and 74 deletions.
diff --git a/lib/src/ast/css/modifiable/node.dart b/lib/src/ast/css/modifiable/node.dart
@@ -17,7 17,7 @@ abstract base class ModifiableCssNode extends CssNode {
  ModifiableCssParentNode? get parent => _parent;
  ModifiableCssParentNode? _parent;
 
- /// The index of [this] in `parent.children`.
  /// The index of `this` in `parent.children`.
  ///
  /// This makes [remove] more efficient.
  int? _indexInParent;
@@ -33,7 33,7 @@ abstract base class ModifiableCssNode extends CssNode {
 
  T accept<T>(ModifiableCssVisitor<T> visitor);
 
- /// Removes [this] from [parent]'s child list.
  /// Removes `this` from [parent]'s child list.
  ///
  /// Throws a [StateError] if [parent] is `null`.
  void remove() {
@@ -65,10 65,10 @@ abstract base class ModifiableCssParentNode extends ModifiableCssNode
  : _children = children,
  children = UnmodifiableListView(children);
 
- /// Returns whether [this] is equal to [other], ignoring their child nodes.
  /// Returns whether `this` is equal to [other], ignoring their child nodes.
  bool equalsIgnoringChildren(ModifiableCssNode other);
 
- /// Returns a copy of [this] with an empty [children] list.
  /// Returns a copy of `this` with an empty [children] list.
  ///
  /// This is *not* a deep copy. If other parts of this node are modifiable,
  /// they are shared between the new and old nodes.

diff --git a/lib/src/ast/sass/at_root_query.dart b/lib/src/ast/sass/at_root_query.dart
@@ -61,7 61,7 @@ final class AtRootQuery {
  {Object? url, Logger? logger, InterpolationMap? interpolationMap}) =>
  AtRootQueryParser(contents, url: url, logger: logger).parse();
 
- /// Returns whether [this] excludes [node].
  /// Returns whether `this` excludes [node].
  ///
  /// @nodoc
  @internal
@@ -76,6 76,6 @@ final class AtRootQuery {
  };
  }
 
- /// Returns whether [this] excludes an at-rule with the given [name].
  /// Returns whether `this` excludes an at-rule with the given [name].
  bool excludesName(String name) => (_all || names.contains(name)) != include;
 }
diff --git a/lib/src/ast/sass/expression/binary_operation.dart b/lib/src/ast/sass/expression/binary_operation.dart
@@ -153,13 153,13 @@ enum BinaryOperator {
  /// The modulo operator, `%`.
  modulo('modulo', '%', 6);
 
- /// The English name of [this].
  /// The English name of `this`.
  final String name;
 
- /// The Sass syntax for [this].
  /// The Sass syntax for `this`.
  final String operator;
 
- /// The precedence of [this].
  /// The precedence of `this`.
  ///
  /// An operator with higher precedence binds tighter.
  final int precedence;

diff --git a/lib/src/ast/sass/expression/list.dart b/lib/src/ast/sass/expression/list.dart
@@ -58,7 58,7 @@ final class ListExpression implements Expression {
  return buffer.toString();
  }
 
- /// Returns whether [expression], contained in [this], needs parentheses when
  /// Returns whether [expression], contained in `this`, needs parentheses when
  /// printed as Sass source.
  bool _elementNeedsParens(Expression expression) => switch (expression) {
  ListExpression(

diff --git a/lib/src/ast/sass/expression/string.dart b/lib/src/ast/sass/expression/string.dart
@@ -23,7 23,7 @@ final class StringExpression implements Expression {
  /// included.
  final Interpolation text;
 
- /// Whether [this] has quotes.
  /// Whether `this` has quotes.
  final bool hasQuotes;
 
  FileSpan get span => text.span;

diff --git a/lib/src/ast/sass/expression/unary_operation.dart b/lib/src/ast/sass/expression/unary_operation.dart
@@ -63,10 63,10 @@ enum UnaryOperator {
  /// The boolean negation operator, `not`.
  not('not', 'not');
 
- /// The English name of [this].
  /// The English name of `this`.
  final String name;
 
- /// The Sass syntax for [this].
  /// The Sass syntax for `this`.
  final String operator;
 
  const UnaryOperator(this.name, this.operator);

diff --git a/lib/src/ast/selector.dart b/lib/src/ast/selector.dart
@@ -83,7 83,7 @@ abstract base class Selector implements AstNode {
 
  Selector(this.span);
 
- /// Prints a warning if [this] is a bogus selector.
  /// Prints a warning if `this` is a bogus selector.
  ///
  /// This may only be called from within a custom Sass function. This will
  /// throw a [SassException] in Dart Sass 2.0.0.

diff --git a/lib/src/ast/selector/list.dart b/lib/src/ast/selector/list.dart
@@ -96,9 96,9 @@ final class SelectorList extends Selector {
  return contents.isEmpty ? null : SelectorList(contents, span);
  }
 
- /// Returns a new selector list that represents [this] nested within [parent].
  /// Returns a new selector list that represents `this` nested within [parent].
  ///
- /// By default, this replaces [ParentSelector]s in [this] with [parent]. If
  /// By default, this replaces [ParentSelector]s in `this` with [parent]. If
  /// [preserveParentSelectors] is true, this instead preserves those selectors
  /// as parent selectors.
  ///

diff --git a/lib/src/ast/selector/pseudo.dart b/lib/src/ast/selector/pseudo.dart
@@ -174,7 174,7 @@ final class PseudoSelector extends SimpleSelector {
  for (var simple in compound) {
  if (simple case PseudoSelector(isElement: true)) {
  // A given compound selector may only contain one pseudo element. If
- // [compound] has a different one than [this], unification fails.
  // [compound] has a different one than `this`, unification fails.
  if (isElement) return null;
 
  // Otherwise, this is a pseudo selector and should come before pseudo

diff --git a/lib/src/ast/selector/simple.dart b/lib/src/ast/selector/simple.dart
@@ -59,7 59,7 @@ abstract base class SimpleSelector extends Selector {
  url: url, logger: logger, allowParent: allowParent)
  .parseSimpleSelector();
 
- /// Returns a new [SimpleSelector] based on [this], as though it had been
  /// Returns a new [SimpleSelector] based on `this`, as though it had been
  /// written with [suffix] at the end.
  ///
  /// Assumes [suffix] is a valid identifier suffix. If this wouldn't produce a

diff --git a/lib/src/async_environment.dart b/lib/src/async_environment.dart
@@ -790,7 790,7 @@ final class AsyncEnvironment {
  return Configuration.implicit(configuration);
  }
 
- /// Returns a module that represents the top-level members defined in [this],
  /// Returns a module that represents the top-level members defined in `this`,
  /// that contains [css] and [preModuleComments] as its CSS, which can be
  /// extended using [extensionStore].
  Module toModule(
@@ -802,7 802,7 @@ final class AsyncEnvironment {
  forwarded: _forwardedModules.andThen((modules) => MapKeySet(modules)));
  }
 
- /// Returns a module with the same members and upstream modules as [this], but
  /// Returns a module with the same members and upstream modules as `this`, but
  /// an empty stylesheet and extension store.
  ///
  /// This is used when resolving imports, since they need to inject forwarded

diff --git a/lib/src/environment.dart b/lib/src/environment.dart
@@ -5,7 5,7 @@
 // DO NOT EDIT. This file was generated from async_environment.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: f7172be68e0a19c4dc2d2ad04fc32a843a98a6bd
 // Checksum: e1beeae58a4d5b97cd7d4f01c7d46b0586b508b9
 //
 // ignore_for_file: unused_import
 
@@ -796,7 796,7 @@ final class Environment {
  return Configuration.implicit(configuration);
  }
 
- /// Returns a module that represents the top-level members defined in [this],
  /// Returns a module that represents the top-level members defined in `this`,
  /// that contains [css] and [preModuleComments] as its CSS, which can be
  /// extended using [extensionStore].
  Module<Callable> toModule(
@@ -808,7 808,7 @@ final class Environment {
  forwarded: _forwardedModules.andThen((modules) => MapKeySet(modules)));
  }
 
- /// Returns a module with the same members and upstream modules as [this], but
  /// Returns a module with the same members and upstream modules as `this`, but
  /// an empty stylesheet and extension store.
  ///
  /// This is used when resolving imports, since they need to inject forwarded

diff --git a/lib/src/extend/extension_store.dart b/lib/src/extend/extension_store.dart
@@ -386,12 386,12 @@ class ExtensionStore {
  }
  }
 
- /// Extends [this] with all the extensions in [extensions].
  /// Extends `this` with all the extensions in [extensions].
  ///
- /// These extensions will extend all selectors already in [this], but they
  /// These extensions will extend all selectors already in `this`, but they
  /// will *not* extend other extensions from [extensionStores].
  void addExtensions(Iterable<ExtensionStore> extensionStores) {
- // Extensions already in [this] whose extenders are extended by
  // Extensions already in `this` whose extenders are extended by
  // [extensions], and thus which need to be updated.
  List<Extension>? extensionsToExtend;
 
@@ -966,8 966,8 @@ class ExtensionStore {
  return specificity;
  }
 
- /// Returns a copy of [this] that extends new selectors, as well as a map
- /// (with reference equality) from the selectors extended by [this] to the
  /// Returns a copy of `this` that extends new selectors, as well as a map
  /// (with reference equality) from the selectors extended by `this` to the
  /// selectors extended by the new [ExtensionStore].
  (ExtensionStore, Map<SelectorList, Box<SelectorList>>) clone() {
  var newSelectors = <SimpleSelector, Set<ModifiableBox<SelectorList>>>{};

diff --git a/lib/src/stylesheet_graph.dart b/lib/src/stylesheet_graph.dart
@@ -385,7 385,7 @@ class StylesheetNode {
  _upstreamImports = newUpstreamImports;
  }
 
- /// Removes [this] as an upstream and downstream node from all the nodes that
  /// Removes `this` as an upstream and downstream node from all the nodes that
  /// import it and that it imports.
  void _remove() {
  for (var node in {...upstream.values, ...upstreamImports.values}) {

diff --git a/lib/src/util/map.dart b/lib/src/util/map.dart
@@ -5,7 5,7 @@
 import 'option.dart';
 
 extension MapExtensions<K, V> on Map<K, V> {
- /// If [this] doesn't contain the given [key], sets that key to [value] and
  /// If `this` doesn't contain the given [key], sets that key to [value] and
  /// returns it.
  ///
  /// Otherwise, calls [merge] with the existing value and [value] and sets

diff --git a/lib/src/util/multi_span.dart b/lib/src/util/multi_span.dart
@@ -70,7 70,7 @@ class MultiSpan implements FileSpan {
  primaryColor: primaryColor,
  secondaryColor: secondaryColor);
 
- /// Returns a copy of [this] with [newPrimary] as its primary span.
  /// Returns a copy of `this` with [newPrimary] as its primary span.
  MultiSpan _withPrimary(FileSpan newPrimary) =>
  MultiSpan._(newPrimary, primaryLabel, secondarySpans);
 }
diff --git a/lib/src/util/nullable.dart b/lib/src/util/nullable.dart
@@ -3,7 3,7 @@
 // https://opensource.org/licenses/MIT.
 
 extension NullableExtension<T> on T? {
- /// If [this] is `null`, returns `null`. Otherwise, runs [fn] and returns its
  /// If `this` is `null`, returns `null`. Otherwise, runs [fn] and returns its
  /// result.
  ///
  /// Based on Rust's `Option.and_then`.

diff --git a/lib/src/util/span.dart b/lib/src/util/span.dart
@@ -84,10 84,10 @@ extension SpanExtensions on FileSpan {
  return subspan(scanner.position).trimLeft();
  }
 
- /// Whether [this] FileSpan contains the [target] FileSpan.
  /// Whether this [FileSpan] contains the [target] FileSpan.
  ///
  /// Validates the FileSpans to be in the same file and for the [target] to be
- /// within [this] FileSpan inclusive range [start,end].
  /// within this [FileSpan]'s inclusive range `[start,end]`.
  bool contains(FileSpan target) =>
  file.url == target.file.url &&
  start.offset <= target.start.offset &&