Specs: Define when needsLayout is reset (also, some unrelated markdown fixes)

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 335 matching lines @@
      //     cache the value
      //     if relativeDimension is true, then mark the value as provisional
      //     return the value
      //   otherwise use the ParsedValue's value; cache it; return it
      // otherwise, if a pseudo-element was specified, try again without one
      // otherwise, if the property is inherited and there's a parent:
      //   get it from the parent (without pseudo); cache it; return it
      // otherwise, get the default value; cache it; return it
 
   readonly attribute Boolean needsLayout; // means that a property with needsLayout:true has changed on this node or one of its descendants
+    // needsLayout is set to false by the ownerLayoutManager's default layout() method
   readonly attribute LayoutManager layoutManager;
 
   readonly attribute LayoutManager ownerLayoutManager; // defaults to the parentNode.layoutManager
     // if you are not the ownerLayoutManager, then ignore this StyleNode in layout() and paintChildren()
     // using walkChildren() does this for you
 
   readonly attribute Boolean needsPaint; // means that either needsLayout is true or a property with needsPaint:true has changed on this node or one of its descendants
     // needsPaint is set to false by the ownerLayoutManager's default paint() method
 
   // only the ownerLayoutManager can change these
@@ skipping 44 matching lines @@
 Layout managers inherit from the following API:
 
 ```javascript
 class LayoutManager {
   readonly attribute StyleNode node;
   constructor LayoutManager(StyleNode node);
 
   void take(StyleNode victim); // sets victim.ownerLayoutManager = this;
     // assert: victim hasn't been take()n yet during this layout
     // assert: victim.needsLayout == true
-    // assert: an ancestor of victim has needsLayout == this (aka, victim is a descendant of this.node)
+    // assert: an ancestor of victim has node.layoutManager == this (aka, victim is a descendant of this.node)
 
   virtual void release(StyleNode victim);
     // called when the StyleNode was removed from the tree
 
   void setChildPosition(child, x, y); // sets child.x, child.y
   void setChildX(child, y); // sets child.x
   void setChildY(child, y); // sets child.y
   void setChildSize(child, width, height); // sets child.width, child.height
   void setChildWidth(child, width); // sets child.width
   void setChildHeight(child, height); // sets child.height
@@ skipping 16 matching lines @@
     // layout() has a forced width and/or height?
 
   virtual LayoutValueRange getIntrinsicWidth(Float? defaultWidth = null);
     // returns min-width, width, and max-width, normalised, defaulting to values given in LayoutValueRange
     // if argument is provided, it overrides width
 
   virtual LayoutValueRange getIntrinsicHeight(Float? defaultHeight = null);
     // returns min-height, height, and max-height, normalised, defaulting to values given in LayoutValueRange
     // if argument is provided, it overrides height
 
+  void markAsLaidOut(); // sets this.node.needsLayout to false
   virtual Dimensions layout(Number? width, Number? height);
-    // returns { }
+    // default implementation calls markAsLaidOut() and returns arguments, with null values resolved to intrinsic dimensions
+    // this should always call this.markAsLaidOut() to reset needsLayout
     // the return value should include the final value for whichever of the width and height arguments that is null
-    // TODO(ianh): should we just grab the width and height from assumeDimensions()?
 
   void markAsPainted(); // sets this.node.needsPaint to false
   virtual void paint(RenderingSurface canvas);
     // set a clip rect on the canvas for rect(0,0,this.width,this.height)
     // call the painter of each property, in order they were registered, which on this element has a painter
     // call this.paintChildren()
     // unset the clip
     // call markAsPainted()
 
   virtual void paintChildren(RenderingSurface canvas);
@@ skipping 58 matching lines @@
 In the constructors for the default elements, they add to themselves
 StyleDeclaration objects as follows:
 
 * ``import``
 * ``template``
 * ``style``
 * ``script``
 * ``content``
 * ``title``
   These all add to themselves the same declaration with value:
-```css
+```javascript
 { display: { value: null } }
 ```
 
 * ``img``
   This adds to itself the declaration with value:
-```css
+```javascript
 { display: { value: sky.ImageElementLayoutManager } }
 ```
 
 * ``span``
 * ``a``
   These all add to themselves the same declaration with value:
-```css
+```javascript
 { display: { value: sky.InlineLayoutManager } }
 ```
 
 * ``iframe``
   This adds to itself the declaration with value:
-```css
+```javascript
 { display: { value: sky.IFrameElementLayoutManager } }
 ```
 
 * ``t``
   This adds to itself the declaration with value:
-```css
+```javascript
 { display: { value: sky.ParagraphLayoutManager } }
 ```
 
 * ``error``
   This adds to itself the declaration with value:
-```css
+```javascript
 { display: { value: sky.ErrorLayoutManager } }
 ```
 
 The ``div`` element doesn't have any default styles.
 
 These declarations are all shared between all the elements (so e.g. if
 you reach in and change the declaration that was added to a ``title``
 element, you're going to change the styles of all the other
 default-hidden elements).