From a28c6560499f9741d6a09f198366442fb39743ec Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Fri, 30 Jul 2021 14:29:51 -0700 Subject: [PATCH 1/3] Add dartdoc categories to Sass APIs --- .gitignore | 1 + CHANGELOG.md | 8 ++++++++ dartdoc_options.yaml | 8 ++++++++ doc/compile.md | 2 ++ doc/importer.md | 5 +++++ doc/value.md | 6 ++++++ lib/sass.dart | 14 ++++++++++++++ lib/src/callable.dart | 2 ++ lib/src/callable/async.dart | 2 ++ lib/src/compile_result.dart | 2 ++ lib/src/exception.dart | 4 ++++ lib/src/importer.dart | 2 ++ lib/src/importer/async.dart | 2 ++ lib/src/importer/filesystem.dart | 2 ++ lib/src/importer/package.dart | 2 ++ lib/src/importer/result.dart | 2 ++ lib/src/logger.dart | 2 ++ lib/src/syntax.dart | 2 ++ lib/src/value.dart | 2 ++ lib/src/value/argument_list.dart | 2 ++ lib/src/value/boolean.dart | 6 ++++++ lib/src/value/color.dart | 2 ++ lib/src/value/function.dart | 2 ++ lib/src/value/list.dart | 4 ++++ lib/src/value/map.dart | 2 ++ lib/src/value/null.dart | 2 ++ lib/src/value/number.dart | 2 ++ lib/src/value/number/complex.dart | 2 ++ lib/src/value/number/single_unit.dart | 2 ++ lib/src/value/number/unitless.dart | 2 ++ lib/src/value/string.dart | 2 ++ lib/src/visitor/serialize.dart | 2 ++ lib/src/warn.dart | 2 ++ 33 files changed, 104 insertions(+) create mode 100644 dartdoc_options.yaml create mode 100644 doc/compile.md create mode 100644 doc/importer.md create mode 100644 doc/value.md diff --git a/.gitignore b/.gitignore index 0208dc2e6..40f791a7e 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,4 @@ pubspec.lock package-lock.json /benchmark/source node_modules/ +/doc/api diff --git a/CHANGELOG.md b/CHANGELOG.md index 19621c819..cced47a55 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/dartdoc_options.yaml b/dartdoc_options.yaml new file mode 100644 index 000000000..7d4ab358b --- /dev/null +++ b/dartdoc_options.yaml @@ -0,0 +1,8 @@ +dartdoc: + categories: + Compile: + markdown: doc/compile.md + Importer: + markdown: doc/importer.md + Value: + markdown: doc/value.md diff --git a/doc/compile.md b/doc/compile.md new file mode 100644 index 000000000..43851ba60 --- /dev/null +++ b/doc/compile.md @@ -0,0 +1,2 @@ +APIs for compiling Sass source files to CSS, and providing options for that +compilation. diff --git a/doc/importer.md b/doc/importer.md new file mode 100644 index 000000000..a1a9bcb4d --- /dev/null +++ b/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 diff --git a/doc/value.md b/doc/value.md new file mode 100644 index 000000000..819d18b0a --- /dev/null +++ b/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 diff --git a/lib/sass.dart b/lib/sass.dart index 8f73c1200..e559b0d38 100644 --- a/lib/sass.dart +++ b/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 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 compileStringToResultAsync(String source, {Syntax? syntax, bool color = false, @@ -296,6 +302,8 @@ Future 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 compileAsync( String path, @@ -421,6 +433,8 @@ Future 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 compileStringAsync( String source, diff --git a/lib/src/callable.dart b/lib/src/callable.dart index 91222f312..f98797d43 100644 --- a/lib/src/callable.dart +++ b/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.') diff --git a/lib/src/callable/async.dart b/lib/src/callable/async.dart index 03fc40948..643013f54 100644 --- a/lib/src/callable/async.dart +++ b/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. diff --git a/lib/src/compile_result.dart b/lib/src/compile_result.dart index ca0b06799..459c899dc 100644 --- a/lib/src/compile_result.dart +++ b/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. diff --git a/lib/src/exception.dart b/lib/src/exception.dart index 8dcb08020..ce2f86414 100644 --- a/lib/src/exception.dart +++ b/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. /// diff --git a/lib/src/importer.dart b/lib/src/importer.dart index 6370db06d..12d626a21 100644 --- a/lib/src/importer.dart +++ b/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. /// diff --git a/lib/src/importer/async.dart b/lib/src/importer/async.dart index cc61c8fb3..912d05084 100644 --- a/lib/src/importer/async.dart +++ b/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. diff --git a/lib/src/importer/filesystem.dart b/lib/src/importer/filesystem.dart index 36192f07a..31af69829 100644 --- a/lib/src/importer/filesystem.dart +++ b/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. diff --git a/lib/src/importer/package.dart b/lib/src/importer/package.dart index fee85228f..cd4b77f40 100644 --- a/lib/src/importer/package.dart +++ b/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:`. diff --git a/lib/src/importer/result.dart b/lib/src/importer/result.dart index 1b3f30dc6..b5b979577 100644 --- a/lib/src/importer/result.dart +++ b/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. diff --git a/lib/src/logger.dart b/lib/src/logger.dart index 56b422c67..d395d8e90 100644 --- a/lib/src/logger.dart +++ b/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(); diff --git a/lib/src/syntax.dart b/lib/src/syntax.dart index a23da9795..eefeceb23 100644 --- a/lib/src/syntax.dart +++ b/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. diff --git a/lib/src/value.dart b/lib/src/value.dart index 95b22e44b..f58ee7c16 100644 --- a/lib/src/value.dart +++ b/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 diff --git a/lib/src/value/argument_list.dart b/lib/src/value/argument_list.dart index 7d2126f2c..3b909c59d 100644 --- a/lib/src/value/argument_list.dart +++ b/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. diff --git a/lib/src/value/boolean.dart b/lib/src/value/boolean.dart index 8c3fc64ad..2ac634449 100644 --- a/lib/src/value/boolean.dart +++ b/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`. diff --git a/lib/src/value/color.dart b/lib/src/value/color.dart index bf65a63a0..b7fa76975 100644 --- a/lib/src/value/color.dart +++ b/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`. diff --git a/lib/src/value/function.dart b/lib/src/value/function.dart index 95bb7a612..a5f949550 100644 --- a/lib/src/value/function.dart +++ b/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. diff --git a/lib/src/value/list.dart b/lib/src/value/list.dart index c4784792d..78fba66b0 100644 --- a/lib/src/value/list.dart +++ b/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. diff --git a/lib/src/value/map.dart b/lib/src/value/map.dart index 989983d72..3f460e71a 100644 --- a/lib/src/value/map.dart +++ b/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 diff --git a/lib/src/value/null.dart b/lib/src/value/null.dart index a3b730a2b..c0d603299 100644 --- a/lib/src/value/null.dart +++ b/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. diff --git a/lib/src/value/number.dart b/lib/src/value/number.dart index c539e5a4a..f27178ea8 100644 --- a/lib/src/value/number.dart +++ b/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 diff --git a/lib/src/value/number/complex.dart b/lib/src/value/number/complex.dart index 8fca749d5..3f6a33a21 100644 --- a/lib/src/value/number/complex.dart +++ b/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 numeratorUnits; diff --git a/lib/src/value/number/single_unit.dart b/lib/src/value/number/single_unit.dart index 581986c52..381f97992 100644 --- a/lib/src/value/number/single_unit.dart +++ b/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; diff --git a/lib/src/value/number/unitless.dart b/lib/src/value/number/unitless.dart index 65c8ed7f8..8e1616826 100644 --- a/lib/src/value/number/unitless.dart +++ b/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 get numeratorUnits => const []; diff --git a/lib/src/value/string.dart b/lib/src/value/string.dart index 616fe94c6..10f5d2e4a 100644 --- a/lib/src/value/string.dart +++ b/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. diff --git a/lib/src/visitor/serialize.dart b/lib/src/visitor/serialize.dart index f9cd02362..0448b4e87 100644 --- a/lib/src/visitor/serialize.dart +++ b/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. diff --git a/lib/src/warn.dart b/lib/src/warn.dart index d84c74a3b..981d0bc6a 100644 --- a/lib/src/warn.dart +++ b/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]; From 9f3133a1791a037d3b4fd58d5bd1e4282b9e023f Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Fri, 30 Jul 2021 15:13:46 -0700 Subject: [PATCH 2/3] Fix dartdoc errors Also fix a couple places where our external API wasn't quite right. --- CHANGELOG.md | 9 ++++++++- lib/sass.dart | 12 ++++++------ lib/src/ast/sass/at_root_query.dart | 1 + lib/src/ast/sass/expression.dart | 1 + lib/src/ast/sass/statement/stylesheet.dart | 5 +++-- lib/src/ast/sass/statement/use_rule.dart | 1 + lib/src/ast/sass/statement/variable_declaration.dart | 1 + lib/src/callable.dart | 5 +++-- lib/src/callable/async.dart | 1 + lib/src/functions/list.dart | 4 ++-- lib/src/importer/package.dart | 3 ++- lib/src/node/value/list.dart | 2 +- lib/src/value.dart | 5 +---- lib/src/value/number.dart | 11 ++++++++++- pubspec.yaml | 2 +- 15 files changed, 42 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cced47a55..3eac11240 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/lib/sass.dart b/lib/sass.dart index e559b0d38..fcce1d4ff 100644 --- a/lib/sass.dart +++ b/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 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 diff --git a/lib/src/ast/sass/at_root_query.dart b/lib/src/ast/sass/at_root_query.dart index 6fb57b3ba..98a7af56e 100644 --- a/lib/src/ast/sass/at_root_query.dart +++ b/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'; diff --git a/lib/src/ast/sass/expression.dart b/lib/src/ast/sass/expression.dart index 3e642f41c..ca802a782 100644 --- a/lib/src/ast/sass/expression.dart +++ b/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'; diff --git a/lib/src/ast/sass/statement/stylesheet.dart b/lib/src/ast/sass/statement/stylesheet.dart index e7c440fe2..99a8e0417 100644 --- a/lib/src/ast/sass/statement/stylesheet.dart +++ b/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'; diff --git a/lib/src/ast/sass/statement/use_rule.dart b/lib/src/ast/sass/statement/use_rule.dart index ffa13a839..5189ca7ee 100644 --- a/lib/src/ast/sass/statement/use_rule.dart +++ b/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'; diff --git a/lib/src/ast/sass/statement/variable_declaration.dart b/lib/src/ast/sass/statement/variable_declaration.dart index 4f401a2a5..caa321f88 100644 --- a/lib/src/ast/sass/statement/variable_declaration.dart +++ b/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'; diff --git a/lib/src/callable.dart b/lib/src/callable.dart index f98797d43..644877d50 100644 --- a/lib/src/callable.dart +++ b/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. diff --git a/lib/src/callable/async.dart b/lib/src/callable/async.dart index 643013f54..6b1038653 100644 --- a/lib/src/callable/async.dart +++ b/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'; diff --git a/lib/src/functions/list.dart b/lib/src/functions/list.dart index 83f85317d..942b2ee8b 100644 --- a/lib/src/functions/list.dart +++ b/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) { diff --git a/lib/src/importer/package.dart b/lib/src/importer/package.dart index cd4b77f40..c88227100 100644 --- a/lib/src/importer/package.dart +++ b/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); diff --git a/lib/src/node/value/list.dart b/lib/src/node/value/list.dart index 836fcacb5..aad45bc72 100644 --- a/lib/src/node/value/list.dart +++ b/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, diff --git a/lib/src/value.dart b/lib/src/value.dart index f58ee7c16..ba95b9722 100644 --- a/lib/src/value.dart +++ b/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 contents, + SassList withListContents(Iterable contents, {ListSeparator? separator, bool? brackets}) { return SassList(contents, separator ?? this.separator, brackets: brackets ?? hasBrackets); diff --git a/lib/src/value/number.dart b/lib/src/value/number.dart index f27178ea8..5e5860286 100644 --- a/lib/src/value/number.dart +++ b/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? 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; diff --git a/pubspec.yaml b/pubspec.yaml index eada8ad45..0a8b08fa3 100644 --- a/pubspec.yaml +++ b/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 From e02d8b4794a94cb500f97dd82890cf6972c729e4 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Fri, 30 Jul 2021 15:25:08 -0700 Subject: [PATCH 3/3] Check for dartdoc warnings in GitHub Actions --- .github/workflows/ci.yml | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index de980bfc5..b0d54914f 100644 --- a/.github/workflows/ci.yml +++ b/.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: