Specs: define registerElement() more carefully; add an 'end tag

sky/specs/apis.md

 APIs
 ====
 
 The Sky core API
 ----------------
 
 ```javascript
 module 'sky:core' {
 
   // EVENTS
@@ skipping 83 matching lines @@
     String getAttribute(String name); // O(N) in number of attributes
     void setAttribute(String name, String value = ''); // O(N) in number of attributes
     void removeAttribute(String name); // O(N) in number of attributes
     
     // Returns a new Array and new Attr instances every time.
     Array<Attr> getAttributes(); // O(N) in number of attributes
 
     readonly attribute ShadowRoot? shadowRoot; // O(1) // returns the shadow root
     Array<ContentElement> getDestinationInsertionPoints(); // O(N) in number of insertion points the node is in
 
+    virtual void endTagParsedCallback(); // noop
     virtual void attributeChangeCallback(String name, String? oldValue, String? newValue); // noop
     // TODO(ianh): does a node ever need to know when it's been redistributed?
   }
 
   class Text : Node {
     constructor (String value = ''); // O(1)
     attribute String value; // O(1)
 
     void replaceWith(String node); // O(1) // special case override of Node.replaceWith()
 
@@ skipping 163 matching lines @@
   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
 
     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:
+    //  0. let prototype be the prototype passed in (defaulting to Element)
+    //  1. let constructor be prototype.constructor
+    //  2. create a new Function that:
+    //      0. throws if not called as a constructor
+    //      1. initialises the shadow tree is shadow on the options is true
+    //      2. calls constructor, if it's not null, with the module as the argument
+    //  3. let that new Function's prototype be the aforementioned prototype
+    //  4. let that new Function have tagName and shadow properties set to
+    //     the values passed in
 
     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 the module's document
   }
@@ skipping 178 matching lines @@
   the core mojo fabric JS API   sky:mojo:fabric:core
   the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread)  sky:mojo:fabric:ipc
   the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed  sky:mojo:shell
   the sky API  sky:core
   the sky debug symbols for private APIs  sky:debug
 ```
 
 TODO(ianh): determine if we want to separate the "this" from the
 Document, especially for Modules, so that exposing a module's element
 doesn't expose the module's exports attribute.