Specs and Docs: minor updates to fix mistakes I found when proof-reading

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 305 matching lines @@
     // for example, TransitioningColorStyleValue would store
     //    {
     //      initial: /* color at time of transition */,
     //      target: /* color at end of transition */,
     //      start: /* time at start of transition */,
     //    }
     // ...which would enable it to update appropriately, and would also
     // let other transitions that come later know that you were half-way
     // through a transition so they can shorten their time accordingly
     //
+    // best practices: if you're storing values on the state object,
+    // then remove the values once they are no longer needed. For
+    // example, when your transition ends, set the object to null.
+    //
     // best practices: if you're a style value that contains multiple
     // style values, then before you call their resolve you should
     // replace the state with a state that is specific to them, and
     // when you get it back you should insert that value into your
     // state somehow. For example, in a resolve()r with two child
     // style values a and b:
     //    let ourState;
     //    if (settings.firstTime)
     //      ourState = { a: null, b: null };
     //    else
     //      ourState = settings.state;
     //    settings.state = ourState.a;
     //    let aResult = a.resolve(node, settings);
     //    ourState.a = settings.state;
     //    settings.state = ourState.b;
     //    let aResult = b.resolve(node, settings);
     //    ourState.b = settings.state;
     //    settings.state = ourState;
     //    return a + b; // or whatever
+    //
+    // best practices: if you're a style value that contains multiple
+    // style values, and all those style values are storing null, then
+    // store null yourself, instead of storing many nulls of your own.
+
+  // attribute Boolean wasStateSet;
+  Boolean getShouldSaveState();
+    // returns true if state is not null, and either state was set
+    // since the last reset, or firstTime is false.
+
 }
 
 class Property : StyleNode {
   constructor (AbstractStyleDeclaration parentNode, PropertyHandle property, AbstractStyleValue? initialValue = null);
   readonly attribute AbstractStyleDeclaration parentNode;
   readonly attribute PropertyHandle property;
   readonly attribute AbstractStyleValue value;
 
   void setValue(AbstractStyleValue? newValue);
     // updates value and calls markDirty()
@@ skipping 145 matching lines @@
     // invoke element.renderNode.cascadedValueDirty(property, pseudoElement); for each
     // currently registered consumer element/pseudoElement pair
 
   void register((Element or RenderNode) consumer, String pseudoElement = ''); // O(1)
   void unregister((Element or RenderNode) consumer, String pseudoElement = ''); // O(N)
     // registers an element/pseudoElement or renderNode/pseudoElement pair with
     // this StyleDeclaration so that a property/value on the style declaration
     // is marked dirty, the relevant render node is informed and can then update
     // its property cache accordingly
 
+
   getter AbstractStyleValue? (PropertyHandle property);
     // looks up the Property object for /property/, and returns its value
     // null if property is missing
 
   setter void (PropertyHandle property, AbstractStyleValue value);
     // verify that value.parentNode is null
     // if there is no Property object for /property/, creates one
     // else calls its update() method to change the value
     // update value's parentNode
     // invoke consumer.renderNode.cascadedValueChanged(property); for each
@@ skipping 100 matching lines @@
   // internal state:
   // - back pointer to backing Node, if we're not a ghost
   // - cache of resolved property values, mapping as follows:
   //    - pseudoElement, property => StyleValue object, resolved value, StyleValueResolverSettings, cascade dirty bit, value dirty bit
   // - property state map (initially empty), as follows:
   //    - pseudoElement, property => object
 
   any getProperty(PropertyHandle property, GetPropertySettings? settings = null);
      // looking at the cached data for the given pseudoElement:
      // if there's a cached value:
-     //   if settings.forceCache is true, return the value
-     //   if neither dirty bit is set, return the cached resolved value
+     //   if settings.forceCache is true, return the cached value
+     //   if neither dirty bit is set, return the cached value
      //   if the cascade dirty bit is not set (value dirty is set) then
      //     resolve the value using the same StyleValue object
      //      - with firstTime=false on the resolver settings
      //      - with the cached state object if any
+     //      - jump to "cache" below
      // if settings.forceCache is true, return null
      // - if there's an override declaration with the property (with
      //   the pseudo or without), then get the value object from there and
      //   jump to "resolve" below.
      // - if there's an element and it has a style declaration with the property
      //   (with the pseudo or without), then get the value object from there
      //   and jump to "resolve" below.
      // - if it's not an inherited property, or if there's no parent, then get the
      //   default value and jump to "resolve" below.
      // - call the parent render node's getProperty() with the same property
      //   but no settings, then cache that value as the value for this element
      //   with the given pseudoElement, with no StyleValue object, no resolver
      //   settings, and set the state to null.
      // resolve:
      //   - get a new resolver settings object
      //   - if the obtained StyleValue object is different than the
      //     cached StyleValue object, or if there is no cached object, then set
      //     the resolver settings to firstTime=true, otherwise it's the same object
      //     and set firstTime=false.
      //   - set the resolver settings' state to the current state for this
      //     pseudoElement/property combination
      //   - using the obtained StyleValue object, call resolve(),
      //     passing it this node and the resolver settings object.
-     //   - update the cache with the obtained value and resolver settings,
-     //     resetting the dirty bits; update the state similarly
+     //   - jump to "cache" below
+     // cache:
+     //   - update the cache with the obtained value and resolver settings
+     //   - reset the dirty bits
+     //   - if the resolver settings' getShouldSaveState() method returns false,
+     //     then discard any cached state, otherwise, cache the new state
 
   readonly attribute RenderNodeStyleDeclarationList overrideStyles;
      // mutable; initially empty
      // this is used when isGhost is true, and can also be used more generally to
      // override styles from the layout manager (e.g. to animate a new node into view)
 
   private void cascadedValueChanged(PropertyHandle property, String pseudoElement = '');
   private void cascadedValueDirty(PropertyHandle property, String pseudoElement = '');
     // - set the appropriate dirty bit on the cached data for this property/pseudoElement pair
     //    - cascade dirty for cascadedValueChanged
@@ skipping 321 matching lines @@
 ```
 
 The other elements don'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 ``span``
 element, you're going to change the styles of all the other
 default-hidden elements). (In other words, in the code snippets above,
 the ``d`` variable is initialised in shared code, and only the
 addStyles() call is per-element.)