Merge pull request #1412 from sass/dartdoc

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,

lib/src/syntax.dart

@@ -6,6 +6,8 @@ import 'package:meta/meta.dart';
 import 'package:path/path.dart' as p;
 
 /// An enum of syntaxes that Sass can parse.
+///
+/// {@category Compile}
 @sealed
 class Syntax {
   /// The CSS-superset SCSS syntax.

lib/src/value.dart

@@ -32,6 +32,8 @@ export 'value/string.dart';
 /// subclass constructors like [new SassString]. Untyped values can be cast to
 /// particular types using `assert*()` functions like [assertString], which
 /// throw user-friendly error messages if they fail.
+///
+/// {@category Value}
 @sealed
 abstract class Value {
   /// Whether the value counts as `true` in an `@if` statement and other
@@ -305,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/argument_list.dart

@@ -11,6 +11,8 @@ import '../value.dart';
 /// An argument list comes from a rest argument. It's distinct from a normal
 /// [SassList] in that it may contain a keyword map as well as the positional
 /// arguments.
+///
+/// {@category Value}
 @sealed
 class SassArgumentList extends SassList {
   /// The keyword arguments attached to this argument list.

lib/src/value/boolean.dart

@@ -8,12 +8,18 @@ import '../visitor/interface/value.dart';
 import '../value.dart';
 
 /// The SassScript `true` value.
+///
+/// {@category Value}
 const sassTrue = SassBoolean._(true);
 
 /// The SassScript `false` value.
+///
+/// {@category Value}
 const sassFalse = SassBoolean._(false);
 
 /// A SassScript boolean value.
+///
+/// {@category Value}
 @sealed
 class SassBoolean extends Value {
   /// Whether this value is `true` or `false`.

lib/src/value/color.dart

@@ -13,6 +13,8 @@ import '../value.dart';
 import '../visitor/interface/value.dart';
 
 /// A SassScript color.
+///
+/// {@category Value}
 @sealed
 class SassColor extends Value {
   /// This color's red channel, between `0` and `255`.

lib/src/value/function.dart

@@ -12,6 +12,8 @@ import '../value.dart';
 ///
 /// A function reference captures a function from the local environment so that
 /// it may be passed between modules.
+///
+/// {@category Value}
 @sealed
 class SassFunction extends Value {
   /// The callable that this function invokes.

lib/src/value/list.dart

@@ -9,6 +9,8 @@ import '../visitor/interface/value.dart';
 import '../value.dart';
 
 /// A SassScript list.
+///
+/// {@category Value}
 @sealed
 class SassList extends Value {
   // TODO(nweiz): Use persistent data structures rather than copying here. An
@@ -70,6 +72,8 @@ class SassList extends Value {
 }
 
 /// An enum of list separator types.
+///
+/// {@category Value}
 @sealed
 class ListSeparator {
   /// A space-separated list.

lib/src/value/map.dart

@@ -9,6 +9,8 @@ import '../value.dart';
 import '../utils.dart';
 
 /// A SassScript map.
+///
+/// {@category Value}
 @sealed
 class SassMap extends Value {
   // TODO(nweiz): Use persistent data structures rather than copying here. We

lib/src/value/null.dart

@@ -6,6 +6,8 @@ import '../visitor/interface/value.dart';
 import '../value.dart';
 
 /// The SassScript `null` value.
+///
+/// {@category Value}
 const Value sassNull = _SassNull();
 
 /// A SassScript null value.

lib/src/value/number.dart

@@ -165,6 +165,8 @@ final _typesByUnit = {
 /// support scientific-style numerator and denominator units (for example,
 /// `miles/hour`). These are expected to be resolved before being emitted to
 /// CSS.
+///
+/// {@category Value}
 @sealed
 abstract class SassNumber extends Value {
   /// The number of distinct digits that are emitted when converting a number to
@@ -194,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].
@@ -257,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;

lib/src/value/number/complex.dart

@@ -10,6 +10,8 @@ import '../number.dart';
 
 /// A specialized subclass of [SassNumber] for numbers that are not
 /// [UnitlessSassNumber]s or [SingleUnitSassNumber]s.
+///
+/// {@category Value}
 @sealed
 class ComplexSassNumber extends SassNumber {
   final List<String> numeratorUnits;

lib/src/value/number/single_unit.dart

@@ -15,6 +15,8 @@ import '../number.dart';
 
 /// A specialized subclass of [SassNumber] for numbers that have exactly one
 /// numerator unit.
+///
+/// {@category Value}
 @sealed
 class SingleUnitSassNumber extends SassNumber {
   final String _unit;

lib/src/value/number/unitless.dart

@@ -10,6 +10,8 @@ import '../../value.dart';
 import '../number.dart';
 
 /// A specialized subclass of [SassNumber] for numbers that have no units.
+///
+/// {@category Value}
 @sealed
 class UnitlessSassNumber extends SassNumber {
   List<String> get numeratorUnits => const [];

lib/src/value/string.dart

@@ -21,6 +21,8 @@ final _emptyUnquoted = SassString("", quotes: false);
 ///
 /// Strings can either be quoted or unquoted. Unquoted strings are usually CSS
 /// identifiers, but they may contain any text.
+///
+/// {@category Value}
 @sealed
 class SassString extends Value {
   /// The contents of the string.

lib/src/visitor/serialize.dart

@@ -1254,6 +1254,8 @@ class _SerializeVisitor
 }
 
 /// An enum of generated CSS styles.
+///
+/// {@category Compile}
 @sealed
 class OutputStyle {
   /// The standard CSS style, with each declaration on its own line.

lib/src/warn.dart

@@ -10,6 +10,8 @@ import 'dart:async';
 /// If [deprecation] is `true`, the warning is emitted as a deprecation warning.
 ///
 /// This may only be called within a custom function or importer callback.
+///
+/// {@category Compile}
 void warn(String message, {bool deprecation = false}) {
   var warnDefinition = Zone.current[#_warn];
 

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