Improve dartdoc and fix a couple API issues

.github/workflows/ci.yml

@@ -127,10 +127,23 @@ jobs:
       - name: Analyze dart
         run: dartanalyzer --fatal-warnings --fatal-infos lib tool test
 
+  dartdoc:
+    name: Dartdoc
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@v1
+      - run: dart pub get
+      - name: Run dartdoc
+        run: dartdoc --quiet --no-generate-docs
+          --errors ambiguous-doc-reference,broken-link,deprecated
+          --errors unknown-directive,unknown-macro,unresolved-doc-reference
+
   sanity_checks:
     name: Sanity checks
     runs-on: ubuntu-latest
-    needs: [sass_spec, dart_tests, node_tests, static_analysis]
+    needs: [sass_spec, dart_tests, node_tests, static_analysis, dartdoc]
     if: "startsWith(github.ref, 'refs/tags/') && github.repository == 'sass/dart-sass'"
 
     steps:

.gitignore

@@ -12,3 +12,4 @@ pubspec.lock
 package-lock.json
 /benchmark/source
 node_modules/
+/doc/api

CHANGELOG.md

@@ -1,3 +1,18 @@
+## 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

dartdoc_options.yaml

@@ -0,0 +1,8 @@
+dartdoc:
+  categories:
+    Compile:
+      markdown: doc/compile.md
+    Importer:
+      markdown: doc/importer.md
+    Value:
+      markdown: doc/value.md

doc/compile.md

@@ -0,0 +1,2 @@
+APIs for compiling Sass source files to CSS, and providing options for that
+compilation.

doc/importer.md

@@ -0,0 +1,5 @@
+Classes for defining custom logic for resolving `@use`, `@forward`, and
+`@import` rules in Sass. See [`Importer`] for details on the importer API
+contract.
+
+[`Importer`]: ../sass/Importer-class.html

doc/value.md

@@ -0,0 +1,6 @@
+Classes that represent Sass values. These are passed to and returned by
+user-defined [`Callable`]s that are passed to functions like
+[`compileToResult()`].
+
+[`Callable`]: ../sass/Callable-class.html
+[`compileToResult()`]: ../sass/compileToResult.html

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
 ///
@@ -89,6 +89,8 @@ export 'src/warn.dart' show warn;
 /// [byte-order mark]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8
 ///
 /// Throws a [SassException] if conversion fails.
+///
+/// {@category Compile}
 CompileResult compileToResult(String path,
         {bool color = false,
         Logger? logger,
@@ -166,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
 ///
@@ -179,6 +181,8 @@ CompileResult compileToResult(String path,
 /// [byte-order mark]: https://en.wikipedia.org/wiki/Byte_order_mark#UTF-8
 ///
 /// Throws a [SassException] if conversion fails.
+///
+/// {@category Compile}
 CompileResult compileStringToResult(String source,
         {Syntax? syntax,
         bool color = false,
@@ -245,6 +249,8 @@ Future<CompileResult> compileToResultAsync(String path,
 /// Running asynchronously allows this to take [AsyncImporter]s rather than
 /// synchronous [Importer]s. However, running asynchronously is also somewhat
 /// slower, so [compileStringToResult] should be preferred if possible.
+///
+/// {@category Compile}
 Future<CompileResult> compileStringToResultAsync(String source,
         {Syntax? syntax,
         bool color = false,
@@ -284,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
@@ -296,6 +302,8 @@ Future<CompileResult> compileStringToResultAsync(String source,
 /// SingleMapping sourceMap;
 /// var css = compile(sassPath, sourceMap: (map) => sourceMap = map);
 /// ```
+///
+/// {@category Compile}
 @Deprecated("Use compileToResult() instead.")
 String compile(
     String path,
@@ -333,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
@@ -345,6 +353,8 @@ String compile(
 /// SingleMapping sourceMap;
 /// var css = compileString(sass, sourceMap: (map) => sourceMap = map);
 /// ```
+///
+/// {@category Compile}
 @Deprecated("Use compileStringToResult() instead.")
 String compileString(
     String source,
@@ -388,6 +398,8 @@ String compileString(
 /// Running asynchronously allows this to take [AsyncImporter]s rather than
 /// synchronous [Importer]s. However, running asynchronously is also somewhat
 /// slower, so [compile] should be preferred if possible.
+///
+/// {@category Compile}
 @Deprecated("Use compileToResultAsync() instead.")
 Future<String> compileAsync(
     String path,
@@ -421,6 +433,8 @@ Future<String> compileAsync(
 /// Running asynchronously allows this to take [AsyncImporter]s rather than
 /// synchronous [Importer]s. However, running asynchronously is also somewhat
 /// slower, so [compileString] should be preferred if possible.
+///
+/// {@category Compile}
 @Deprecated("Use compileStringToResultAsync() instead.")
 Future<String> compileStringAsync(
     String source,

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.
@@ -62,6 +63,8 @@ export 'callable/user_defined.dart';
 ///   [SassString.sassIndexToRuneIndex] methods can be used to do this
 ///   automatically, and the [SassString.sassLength] getter can be used to
 ///   access a string's length in code points.
+///
+/// {@category Compile}
 @sealed
 abstract class Callable extends AsyncCallable {
   @Deprecated('Use `Callable.function` instead.')

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';
 
@@ -17,6 +18,8 @@ import 'async_built_in.dart';
 /// work synchronously, it should be a [Callable] instead.
 ///
 /// See [Callable] for more details.
+///
+/// {@category Compile}
 @sealed
 abstract class AsyncCallable {
   /// The callable's name.

lib/src/compile_result.dart

@@ -10,6 +10,8 @@ import 'visitor/serialize.dart';
 
 /// The result of compiling a Sass document to CSS, along with metadata about
 /// the compilation process.
+///
+/// {@category Compile}
 @sealed
 class CompileResult {
   /// The result of evaluating the source file.

lib/src/exception.dart

@@ -3,6 +3,7 @@
 // https://opensource.org/licenses/MIT.
 
 import 'package:charcode/charcode.dart';
+import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 import 'package:stack_trace/stack_trace.dart';
 import 'package:term_glyph/term_glyph.dart' as term_glyph;
@@ -12,6 +13,9 @@ import 'utils.dart';
 import 'value.dart';
 
 /// An exception thrown by Sass.
+///
+/// {@category Compile}
+@sealed
 class SassException extends SourceSpanException {
   /// The Sass stack trace at the point this exception was thrown.
   ///

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.dart

@@ -24,6 +24,8 @@ export 'importer/result.dart';
 /// [AsyncImporter] if possible.
 ///
 /// Subclasses should extend [Importer], not implement it.
+///
+/// {@category Importer}
 abstract class Importer extends AsyncImporter {
   /// An importer that never imports any stylesheets.
   ///

lib/src/importer/async.dart

@@ -22,6 +22,8 @@ import 'utils.dart' as utils;
 /// instead.
 ///
 /// Subclasses should extend [AsyncImporter], not implement it.
+///
+/// {@category Importer}
 abstract class AsyncImporter {
   /// Whether the current [canonicalize] invocation comes from an `@import`
   /// rule.

lib/src/importer/filesystem.dart

@@ -12,6 +12,8 @@ import '../util/nullable.dart';
 import 'utils.dart';
 
 /// An importer that loads files from a load path on the filesystem.
+///
+/// {@category Importer}
 @sealed
 class FilesystemImporter extends Importer {
   /// The path relative to which this importer looks for files.

lib/src/importer/package.dart

@@ -14,6 +14,8 @@ import '../importer.dart';
 final _filesystemImporter = FilesystemImporter('.');
 
 /// An importer that loads stylesheets from `package:` imports.
+///
+/// {@category Importer}
 @sealed
 class PackageImporter extends Importer {
   /// The resolver that converts `package:` imports to `file:`.
@@ -24,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/importer/result.dart

@@ -10,6 +10,8 @@ import '../importer.dart';
 import '../syntax.dart';
 
 /// The result of importing a Sass stylesheet, as returned by [Importer.load].
+///
+/// {@category Importer}
 @sealed
 class ImporterResult {
   /// The contents of the stylesheet.

lib/src/logger.dart

@@ -10,6 +10,8 @@ import 'logger/stderr.dart';
 /// An interface for loggers that print messages produced by Sass stylesheets.
 ///
 /// This may be implemented by user code.
+///
+/// {@category Compile}
 abstract class Logger {
   /// A logger that silently ignores all messages.
   static final Logger quiet = _QuietLogger();

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,