Use @internal to cordon off internal-only Value APIs (#1379)

Lays the groundwork for #236

Note that we need to add a bunch of explicit @Nodoc annotations to
work around dart-lang/dartdoc#2418 and dart-lang/dartdoc#2419.

Author: nex3

CHANGELOG.md

@@ -22,6 +22,11 @@
 * Fix a race condition where `meta.load-css()` could trigger an internal error
   when running in asynchronous mode.
 
+### Dart API
+
+* Use the `@internal` annotation to indicate which `Value` APIs are available
+  for public use.
+
 ## 1.35.1
 
 * Fix a bug where the quiet dependency flag didn't silence warnings in some

lib/sass.dart

@@ -24,8 +24,7 @@ export 'src/exception.dart' show SassException;
 export 'src/importer.dart';
 export 'src/logger.dart';
 export 'src/syntax.dart';
-export 'src/value.dart' show ListSeparator;
-export 'src/value/external/value.dart';
+export 'src/value.dart';
 export 'src/visitor/serialize.dart' show OutputStyle;
 export 'src/warn.dart' show warn;
 

lib/src/callable.dart

@@ -7,7 +7,6 @@ import 'package:meta/meta.dart';
 import 'callable/async.dart';
 import 'callable/built_in.dart';
 import 'value.dart';
-import 'value/external/value.dart' as ext;
 
 export 'callable/async.dart';
 export 'callable/async_built_in.dart';
@@ -67,7 +66,7 @@ export 'callable/user_defined.dart';
 abstract class Callable extends AsyncCallable {
   @Deprecated('Use `Callable.function` instead.')
   factory Callable(String name, String arguments,
-          ext.Value callback(List<ext.Value> arguments)) =>
+          Value callback(List<Value> arguments)) =>
       Callable.function(name, arguments, callback);
 
   /// Creates a function with the given [name] and [arguments] that runs
@@ -113,7 +112,6 @@ abstract class Callable extends AsyncCallable {
   /// which provides access to keyword arguments using
   /// [SassArgumentList.keywords].
   factory Callable.function(String name, String arguments,
-          ext.Value callback(List<ext.Value> arguments)) =>
-      BuiltInCallable.function(
-          name, arguments, (arguments) => callback(arguments) as Value);
+          Value callback(List<Value> arguments)) =>
+      BuiltInCallable.function(name, arguments, callback);
 }

lib/src/callable/async.dart

@@ -7,7 +7,6 @@ import 'dart:async';
 import 'package:meta/meta.dart';
 
 import '../value.dart';
-import '../value/external/value.dart' as ext;
 import 'async_built_in.dart';
 
 /// An interface for functions and mixins that can be invoked from Sass by
@@ -25,7 +24,7 @@ abstract class AsyncCallable {
 
   @Deprecated('Use `AsyncCallable.function` instead.')
   factory AsyncCallable(String name, String arguments,
-          FutureOr<ext.Value> callback(List<ext.Value> arguments)) =>
+          FutureOr<Value> callback(List<Value> arguments)) =>
       AsyncCallable.function(name, arguments, callback);
 
   /// Creates a callable with the given [name] and [arguments] that runs
@@ -36,10 +35,6 @@ abstract class AsyncCallable {
   ///
   /// See [new Callable] for more details.
   factory AsyncCallable.function(String name, String arguments,
-          FutureOr<ext.Value> callback(List<ext.Value> arguments)) =>
-      AsyncBuiltInCallable.function(name, arguments, (arguments) {
-        var result = callback(arguments);
-        if (result is ext.Value) return result as Value;
-        return result.then((value) => value as Value);
-      });
+          FutureOr<Value> callback(List<Value> arguments)) =>
+      AsyncBuiltInCallable.function(name, arguments, callback);
 }

lib/src/exception.dart

@@ -78,7 +78,7 @@ body::before {
   }
 }
 
-/// A [SassException] that's also a [MultiSpanSassException].
+/// A [SassException] that's also a [MultiSourceSpanException].
 class MultiSpanSassException extends SassException
     implements MultiSourceSpanException {
   final String primaryLabel;

lib/src/functions/meta.dart

@@ -40,7 +40,7 @@ final global = UnmodifiableListView([
     if (value is SassColor) return SassString("color", quotes: false);
     if (value is SassList) return SassString("list", quotes: false);
     if (value is SassMap) return SassString("map", quotes: false);
-    if (value is SassNull) return SassString("null", quotes: false);
+    if (value == sassNull) return SassString("null", quotes: false);
     if (value is SassNumber) return SassString("number", quotes: false);
     if (value is SassFunction) return SassString("function", quotes: false);
     assert(value is SassString);

lib/src/node/exports.dart

@@ -14,7 +14,7 @@ class Exports {
   external set renderSync(Function function);
   external set info(String info);
   external set types(Types types);
-  external set NULL(SassNull sassNull);
+  external set NULL(Value sassNull);
   external set TRUE(SassBoolean sassTrue);
   external set FALSE(SassBoolean sassFalse);
 }