Add dartdoc categories to Sass APIs

.gitignore

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

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.36.1
+
+### Dart API
+
+* **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.
+
 ## 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

@@ -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,
@@ -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,
@@ -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,
@@ -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/callable.dart

@@ -62,6 +62,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

@@ -17,6 +17,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/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:`.

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/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

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

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];