Specs: Split apis.md into dom.md, events.md, idl.md, and move the remainder into README.md and modu…

sky/specs/idl.md

Index: sky/specs/idl.md
diff --git a/sky/specs/idl.md b/sky/specs/idl.md
new file mode 100644
index 0000000000000000000000000000000000000000..9cb185f6eb333d149ee686b7beeff6683f90f2ff
--- /dev/null
+++ b/sky/specs/idl.md
@@ -0,0 +1,158 @@
+Sky IDL
+=======
+
+The Sky IDL language is used to describe JS APIs found in Sky, in
+particular, the JS APIs exposed by the four magical imports defined in
+this document.
+
+Sky IDL definitions are typically compiled to C++ that exposes the C++
+implementations of the APIs to JavaScript.
+
+Sky IDL works more or less the same as Web IDL but the syntax is a bit
+different.
+
+```javascript
+module 'sky:modulename' {
+
+  // this is a comment
+
+  typedef NewType OldType; // useful when OldType is a commonly-used union
+
+  callback CallbackName ReturnType (ArgumentType argumentName);
+
+  class ClassName {
+    // a class corresponds to a JavaScript prototype
+    // corresponds to a WebIDL 'interface'
+  }
+
+  abstract class Superclass {
+    // an abstract class can't have a non-abstract constructor
+    // an abstract class may have abstract constructors and methods
+    // an abstract class may have everything else a class can have
+
+    abstract constructor ();
+      // this indicates that non-abstract subclasses must have a constructor with the given arguments
+
+    abstract ReturnType methodCallback();
+      // this method does nothing, but is included to describe the interface that subclasses will implement
+      // a non-abstract class must have an explicit implementation of all inherited abstract methods
+    
+  }
+
+  class Subclass : Superclass {
+    // properties
+    readonly attribute ReturnType attributeName; // getter
+    attribute ReturnType attributeName; // getter and setter
+
+    // methods and constructors
+    constructor ();
+    ReturnType method();
+      // When the platform calls this method, it always invokes the "real" method, even if it's been
+      // deleted from the prototypes (as if it took a reference to the method at startup, and stored
+      // state using Symbols)
+      // Calling a method with fewer arguments than defined will throw.
+      // Calling a method with more arguments ignores the extra arguments.
+    virtual ReturnType methodCallback();
+      // when the platform calls this, it actually calls it the way JS would, so author overrides do
+      // affect what gets called. Make sure if you override it that you call the superclass implementation!
+      // The default implementations of 'virtual' methods all end by calling the identically named method
+      // on the superclass, if there is such a method.
+
+    // non-abstract classes cannot have abstract constructors or methods, and in particular, must
+    // have explicit non-abstract versions of any inherited abstract constructors or methods
+
+    // properties on the constructor
+    constructor readonly attribute ReturnType staticName;
+
+    // private APIs - see below
+    private void method();
+
+    // arguments and overloading are done as follows
+    // note that the argument names are only for documentation purposes
+    ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2);
+    // the last argument's type can have "..." appended to it to indicate a varargs-like situation
+    ReturnType method(ArgumentType argumentName1, ArgumentType... allSubsequentArguments);
+    // trailing arguments can have a default value, which must be a literal of the given type
+    ReturnType method(ArgumentType argumentName1, ArgumentType argumentName2 = defaultValue);
+  }
+
+  dictionary Options {
+    String foo; // if there's no default, the property must be specified or it's a TypeError
+    Integer bar = 4; // properties can have default values
+  }
+
+  // the module can have properties and methods also
+  attribute String Foo;
+  void method();
+
+  interface InterfaceName {
+    // describes a template of a prototype, in the same syntax as a class
+    // not actually exposed in the runtime
+  }
+
+}
+```
+
+### Private APIs ###
+
+Private APIs are only accessible via Symbol objects, which are then
+exposed on the sky:debug module's exports object as the name of the
+member given in the IDL.
+
+For example, consider:
+
+```javascript
+class Foo {
+  private void Bar();
+}
+```
+
+In a script with a ``foo`` object of type ``Foo``, ``foo.Bar`` is
+undefined. However, it can be obtained as follows:
+
+```html
+<import src="sky:debug" as="debug"/>
+<!-- ... import whatever defines 'foo' ... -->
+<script>
+  foo[debug.Bar]
+</script>
+```
+
+### Types ###
+
+The following types are available:
+
+* ``Integer`` - WebIDL ``long long``
+* ``Float`` - WebIDL ``double``
+* ``Infinity`` - singleton type with value ``Infinity``
+* ``String`` - WebIDL ``USVString``
+* ``Boolean`` - WebIDL ``boolean``
+# ``Object`` - WebIDL ``object`` (``ClassName`` can be used as a literal for this type)
+* ``ClassName`` - an instance of the class ClassName
+* ``Class<ClassName>`` - a class ClassName or one of its subclasses (not an instance)
+* ``DictionaryName`` - an instance of the dictionary DictionaryName
+* ``Promise<Type>`` - WebIDL ``Promise<T>``
+* ``Generator<Type>`` - An ECMAScript generator function that returns data of the given type
+* ``Array<Type>`` - WebIDL ``sequence<T>``
+* ``Dictionary<Type>`` - unordered set of name-value String-Type pairs with no duplicate names
+* ``Type?`` - union of Type and the singleton type with value ``null`` (WebIDL nullable)
+* ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
+* ``any`` - union of all types (WebIDL ``any``)
+
+Methods that return nothing (undefined, in JS) use the keyword "void"
+instead of a type.
+
+
+TODO(ianh): Define in detail how this actually works
+
+
+Mojom IDL
+---------
+
+The Mojom IDL language is used to describe the APIs exposed over Mojo
+pipes.
+
+Mojom IDL definitions are typically compiled to wrappers in each
+language, which are then used as imports.
+
+TODO(ianh): Define in detail how this actually works