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

sky/specs/modules.md

 Sky Module System
 =================
 
 This document describes the Sky module system.
 
 Overview
 --------
 
 The Sky module system is based on the ``import`` element. In its
 most basic form, you import a module as follows:
@@ skipping 29 matching lines @@
 could be set to the module's Document itself, in case the point of the
 module is to expose some ``template`` elements.
 
 ### Exporting element definitions ###
 
 When importing a module into another, Sky looks at the properties on
 the imported module's ``exports`` value, and for each property that is
 an element constructor (generated by ``registerElement()``), it adds
 an element to the importee's element registry.
 
+### IDL ###
+
+```javascript
+abstract class AbstractModule : EventTarget {
+  readonly attribute Document document; // O(1) // the Documentof the module or application
+  Promise<any> import(String url); // O(Yikes) // returns the module's exports
+  private Array<Module> getImports(); O(N) // returns the Module objects of all the imported modules
+
+  readonly attribute String url;
+
+  ElementConstructor registerElement(ElementRegistration options); // O(1)
+  // if you call registerElement() with an object that was created by
+  // registerElement(), it just returns the object after registering it,
+  // rather than creating a new constructor
+  // otherwise, it proceeds as follows:
+  //  1. let constructor be the constructor passed in, if any
+  //  2. let prototype be the constructor's prototype; if there is no
+  //     constructor, let prototype be Element
+  //  3. create a new Function that:
+  //      1. throws if not called as a constructor
+  //      2. creates an actual Element object
+  //      3. initialises the shadow tree if shadow on the options is true
+  //      4. calls constructor, if it's not null, with the module as the argument
+  //  4. let that new Function's prototype be the aforementioned prototype
+  //  5. let that new Function have tagName and shadow properties set to
+  //     the values passed in on options
+  //  6. register the new element
+
+  readonly attribute ScriptElement? currentScript; // O(1) // returns the <script> element currently being executed if any, and if it's in this module; else null
+}
+
+class Module : AbstractModule {
+  constructor (Application application, Document document, String url); // O(1)
+  readonly attribute Application application; // O(1)
+
+  attribute any exports; // O(1) // defaults to {}
+}
+
+class Application : AbstractModule {
+  constructor (Document document, String url); // O(1)
+  attribute String title; // O(1)
+}
+```
+
  
 Naming modules
 --------------
 
 The ``as`` attribute on the ``import`` element binds a name to the
 imported module:
 
 ```html
 <import src="path/to/chocolate.sky" as="chocolate" />
 ```
 
 The parser executes the contents of script elements inside a module as
 if they were executed as follow:
 
 ```javascript
 (new Function(name_1, ..., name_n, module, source_code)).call(
   value_1, ..., value_n, source_module);
 ```
 
 Where ``name_1`` through ``name_n`` are the names bound to the
 various named imports in the script element's document,
 ``source_code`` is the text content of the script element,
 ``source_module`` is the ``Module`` object of the script element's
 module, and ``value_1`` through ``value_n`` are the values
 exported by the various named imports in the script element's
 document.
 
 When an import fails to load, the ``as`` name for the import gets
 bound to ``undefined``.