Fix dartdoc errors

Also fix a couple places where our external API wasn't quite right.

Author: nex3

CHANGELOG.md

@@ -1,11 +1,18 @@
-## 1.36.1
+## 1.37.0
 
 ### Dart API
 
+* **Potentially breaking bug fix:** `SassNumber.asSlash`,
+  `SassNumber.withSlash()`, and `SassNumber.withoutSlash()` have been marked as
+  `@internal`. They were never intended to be used outside the `sass` package.
+
 * **Potentially breaking bug fix:** `SassException` has been marked as `@sealed`
   to formally indicate that it's not intended to be extended outside of the
   `sass` package.
 
+* Add a `Value.withListContents()` method that returns a new Sass list with the
+  same list separator and brackets as the current value, interpreted as a list.
+
 ## 1.36.0
 
 ### Dart API

lib/sass.dart

@@ -76,8 +76,8 @@ export 'src/warn.dart' show warn;
 /// correspond to which in the resulting CSS. [SingleMapping.targetUrl] will be
 /// `null`. It's up to the caller to save this mapping to disk and add a source
 /// map comment to [CompileResult.css] pointing to it. Users using the
-/// [SourceMap] API should be sure to add the [`source_maps`][] package to their
-/// pubspec.
+/// [SingleMapping] API should be sure to add the [`source_maps`][] package to
+/// their pubspec.
 ///
 /// [`source_maps`]: https://pub.dartlang.org/packages/source_maps
 ///
@@ -168,8 +168,8 @@ CompileResult compileToResult(String path,
 /// correspond to which in the resulting CSS. [SingleMapping.targetUrl] will be
 /// `null`. It's up to the caller to save this mapping to disk and add a source
 /// map comment to [CompileResult.css] pointing to it. Users using the
-/// [SourceMap] API should be sure to add the [`source_maps`][] package to their
-/// pubspec.
+/// [SingleMapping] API should be sure to add the [`source_maps`][] package to
+/// their pubspec.
 ///
 /// [`source_maps`]: https://pub.dartlang.org/packages/source_maps
 ///
@@ -290,7 +290,7 @@ Future<CompileResult> compileStringToResultAsync(String source,
 /// sections of the source file(s) correspond to which in the resulting CSS.
 /// It's called immediately before this method returns, and only if compilation
 /// succeeds. Note that [SingleMapping.targetUrl] will always be `null`. Users
-/// using the [SourceMap] API should be sure to add the [`source_maps`][]
+/// using the [SingleMapping] API should be sure to add the [`source_maps`][]
 /// package to their pubspec.
 ///
 /// [`source_maps`]: https://pub.dartlang.org/packages/source_maps
@@ -341,7 +341,7 @@ String compile(
 /// sections of the source file(s) correspond to which in the resulting CSS.
 /// It's called immediately before this method returns, and only if compilation
 /// succeeds. Note that [SingleMapping.targetUrl] will always be `null`. Users
-/// using the [SourceMap] API should be sure to add the [`source_maps`][]
+/// using the [SingleMapping] API should be sure to add the [`source_maps`][]
 /// package to their pubspec.
 ///
 /// [`source_maps`]: https://pub.dartlang.org/packages/source_maps

lib/src/ast/sass/at_root_query.dart

@@ -4,6 +4,7 @@
 
 import 'package:collection/collection.dart';
 
+import '../../exception.dart';
 import '../../logger.dart';
 import '../../parse/at_root_query.dart';
 import '../css.dart';

lib/src/ast/sass/expression.dart

@@ -2,6 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
+import '../../exception.dart';
 import '../../logger.dart';
 import '../../parse/scss.dart';
 import '../../visitor/interface/expression.dart';

lib/src/ast/sass/statement/stylesheet.dart

@@ -6,16 +6,17 @@ import 'dart:collection';
 
 import 'package:source_span/source_span.dart';
 
-import '../../../visitor/interface/statement.dart';
+import '../../../exception.dart';
 import '../../../logger.dart';
 import '../../../parse/css.dart';
 import '../../../parse/sass.dart';
 import '../../../parse/scss.dart';
 import '../../../syntax.dart';
+import '../../../visitor/interface/statement.dart';
 import '../statement.dart';
-import 'parent.dart';
 import 'forward_rule.dart';
 import 'loud_comment.dart';
+import 'parent.dart';
 import 'silent_comment.dart';
 import 'use_rule.dart';
 import 'variable_declaration.dart';

lib/src/ast/sass/statement/use_rule.dart

@@ -4,6 +4,7 @@
 
 import 'package:source_span/source_span.dart';
 
+import '../../../exception.dart';
 import '../../../logger.dart';
 import '../../../parse/scss.dart';
 import '../../../visitor/interface/statement.dart';

lib/src/ast/sass/statement/variable_declaration.dart

@@ -4,6 +4,7 @@
 
 import 'package:source_span/source_span.dart';
 
+import '../../../exception.dart';
 import '../../../logger.dart';
 import '../../../parse/scss.dart';
 import '../../../utils.dart';

lib/src/callable.dart

@@ -6,6 +6,7 @@ import 'package:meta/meta.dart';
 
 import 'callable/async.dart';
 import 'callable/built_in.dart';
+import 'exception.dart';
 import 'value.dart';
 
 export 'callable/async.dart';
@@ -41,8 +42,8 @@ export 'callable/user_defined.dart';
 /// * When manipulating values like lists, strings, and numbers that have
 ///   metadata (comma versus space separated, bracketed versus unbracketed,
 ///   quoted versus unquoted, units), the output metadata should match the input
-///   metadata. For lists, the [Value.changeList] method can be used to do this
-///   automatically.
+///   metadata. For lists, the [Value.withListContents] method can be used to do
+///   this automatically.
 ///
 /// * When in doubt, lists should default to comma-separated, strings should
 ///   default to quoted, and number should default to unitless.

lib/src/callable/async.dart

@@ -6,6 +6,7 @@ import 'dart:async';
 
 import 'package:meta/meta.dart';
 
+import '../exception.dart';
 import '../value.dart';
 import 'async_built_in.dart';
 

lib/src/functions/list.dart

@@ -38,7 +38,7 @@ final _setNth = _function("set-nth", r"$list, $n, $value", (arguments) {
   var value = arguments[2];
   var newList = list.asList.toList();
   newList[list.sassIndexToListIndex(index, "n")] = value;
-  return arguments[0].changeListContents(newList);
+  return arguments[0].withListContents(newList);
 });
 
 final _join = _function(
@@ -99,7 +99,7 @@ final _append =
   }
 
   var newList = [...list.asList, value];
-  return list.changeListContents(newList, separator: separator);
+  return list.withListContents(newList, separator: separator);
 });
 
 final _zip = _function("zip", r"$lists...", (arguments) {

lib/src/importer/package.dart

@@ -26,7 +26,8 @@ class PackageImporter extends Importer {
   /// package.
   ///
   /// [`PackageConfig`]: https://pub.dev/documentation/package_config/latest/package_config.package_config/PackageConfig-class.html
-  PackageImporter(this._packageConfig);
+  PackageImporter(PackageConfig packageConfig)
+  : _packageConfig = packageConfig;
 
   Uri? canonicalize(Uri url) {
     if (url.scheme == 'file') return _filesystemImporter.canonicalize(url);

lib/src/node/value/list.dart

@@ -34,7 +34,7 @@ final Function listConstructor = createClass('SassList',
   'setValue': (_NodeSassList thisArg, int index, Object value) {
     var mutable = thisArg.dartValue.asList.toList();
     mutable[index] = unwrapValue(value);
-    thisArg.dartValue = thisArg.dartValue.changeListContents(mutable);
+    thisArg.dartValue = thisArg.dartValue.withListContents(mutable);
   },
   'getSeparator': (_NodeSassList thisArg) =>
       thisArg.dartValue.separator == ListSeparator.comma,

lib/src/value.dart

@@ -307,10 +307,7 @@ abstract class Value {
 
   /// Returns a new list containing [contents] that defaults to this value's
   /// separator and brackets.
-  ///
-  /// @nodoc
-  @internal
-  SassList changeListContents(Iterable<Value> contents,
+  SassList withListContents(Iterable<Value> contents,
       {ListSeparator? separator, bool? brackets}) {
     return SassList(contents, separator ?? this.separator,
         brackets: brackets ?? hasBrackets);

lib/src/value/number.dart

@@ -196,6 +196,9 @@ abstract class SassNumber extends Value {
 
   /// The representation of this number as two slash-separated numbers, if it
   /// has one.
+  ///
+  /// @nodoc
+  @internal
   final Tuple2<SassNumber, SassNumber>? asSlash;
 
   /// Whether [this] is an integer, according to [fuzzyEquals].
@@ -259,10 +262,16 @@ abstract class SassNumber extends Value {
   SassNumber withValue(num value);
 
   /// Returns a copy of [this] without [asSlash] set.
+  ///
+  /// @nodoc
+  @internal
   SassNumber withoutSlash() => asSlash == null ? this : withValue(value);
 
-  /// Returns a copy of [this] with [this.asSlash] set to a tuple containing
+  /// Returns a copy of [this] with [asSlash] set to a tuple containing
   /// [numerator] and [denominator].
+  ///
+  /// @nodoc
+  @internal
   SassNumber withSlash(SassNumber numerator, SassNumber denominator);
 
   SassNumber assertNumber([String? name]) => this;

pubspec.yaml

@@ -1,5 +1,5 @@
 name: sass
-version: 1.36.0
+version: 1.37.0
 description: A Sass implementation in Dart.
 author: Sass Team
 homepage: https://github.com/sass/dart-sass