Specs: dartification of dom.md, more work on script.md; this is highly work-in-progress and hasn't …

sky/specs/script.md

Index: sky/specs/script.md
diff --git a/sky/specs/script.md b/sky/specs/script.md
index 5aa0f8c9726ef961f2f092467a0fd6cbc8f162b9..debe791d8e0963f8dde39b1ffd002984a4a5aa7e 100644
--- a/sky/specs/script.md
+++ b/sky/specs/script.md
@@ -1,15 +1,32 @@
 Sky Script Language
 ===================
 
-The Sky script language is based on Dart.
+The Sky script language is Dart.
 
-It has the following differences from Dart:
+The way that Sky integrates the module system with its script language
+is described in [modules.md](modules.md).
 
-- the 'library', 'part', 'import', 'export', and 'part of' directives
-  are not supported in sky (sky has its own module system)
+When an method defined as ``external`` receives an argument, it must
+type-check it, and, if the argument's value is the wrong type, then it
+must throw an ArgumentError as follows:
 
-- ``<script>`` elements parse ``topLevelDefinition``s (there is no
-  ``libraryDefinition`` construct in the Sky Script Language).
+   throw new ArgumentError(value, name: name);
 
-The way that Sky integrates the module system with its script language
-is described in [modules.md](modules.md).
+...where "name" is the name of the argument.
+
+Further, if the type of the argument is annotated with ``@nonnull``,
+then the method must additionally throw if the value is of type Null,
+as follows:
+
+   throw new ArgumentError.notNull(name);
+
+The ``@nonnull`` annotation is defined as follows:
+
+```dart
+const nonnull = const Object();
+```
+
+The ``@nonnull`` annotation does nothing in code not marked
+``external``, but it has been included anyway for documentation
+purposes. It indicates places where providing a null is a contract
+violation and that results are therefore likely to be poor.