Merge pull request #4950 from kant/patch-2

Semantic issue (proposal) plus minor fixes

README.md

@@ -398,7 +398,7 @@ Polymer 2.0 elements will stamp their templates into shadow roots created using
 #### Scoped styling
 
 * <a name="breaking-styling-content"></a>`::content` CSS pseudo-selectors must be changed to `::slotted`, and may only target immediate children and use no descendant selectors
-* <a name="breaking-styling-host-context"></a>`:host-context()` pseudo-selectors have been removed. These were primarily useful for writing bidi rules (e.g. `:host-context([dir=rtl])`); these should be replaced with the [new `:dir(rtl)` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir), which we plan to polyfill in the [styling shim](https://github.com/webcomponents/shadycss) soon
+* <a name="breaking-styling-host-context"></a>`:host-context()` pseudo-selectors have been removed. These were primarily useful for writing bi-directional rules (e.g. `:host-context([dir=rtl])`); these should be replaced with the [new `:dir(rtl)` selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir), which we plan to polyfill in the [styling shim](https://github.com/webcomponents/shadycss) soon
 * <a name="breaking-deep"></a>The previously deprecated `/deep/` and `::shadow` selectors have been completely removed from V1 native support and must not be used (use [CSS custom properties](https://www.polymer-project.org/1.0/docs/devguide/styling#custom-css-properties) to customize styling instead)
 
 #### Scoped events
@@ -462,7 +462,7 @@ Polymer 2.0 will continue to use a [shim](https://github.com/webcomponents/shady
   * `@apply(--foo)`
     * Should be `@apply --foo;`
 * <a name="breaking-customStyle"></a>`element.customStyle` as an object that can be assigned to has been removed; use `element.updateStyles({...})` instead.
-* <a name="breaking-style-location"></a>`<style>` inside of a `<dom-module>`, but outside of `<template>` is no longer supported
+* <a name="breaking-style-location"></a>`<style>` inside of a `<dom-module>`, but outside of `<template>` is no longer supported.
 
 ### Data system
 * <a name="breaking-data-init"></a>An element's template is not stamped & data system not initialized (observers, bindings, etc.) until the element has been connected to the main document.  This is a direct result of the V1 changes that prevent reading attributes in the constructor.
@@ -476,7 +476,7 @@ Polymer 2.0 will continue to use a [shim](https://github.com/webcomponents/shady
 * <a name="breaking-method-args"></a>Multi-property observers, computed methods, and computed bindings are now called once at initialization if any arguments are defined (and will see `undefined` for any undefined arguments).  As such, the [1.x rule requiring all properties of a multi-property observer to be defined](https://www.polymer-project.org/1.0/docs/devguide/observers#multi-property-observers) no longer applies, as this was a major source of confusion and unintended consequences.  Subsequently setting multi-property method arguments will cause the method to be called once for each property changed via accessors, or once per batch of changes via `setProperties({...})`.
 * <a name="breaking-dynamic-functions"> Declaring a method name used as an observer or computing function in the `properties` block causes the method property itself to become a dependency for any effects it is used in, meaning the effect for that method will run whenever the method is set, similar to 1.x. However, due to removing the `undefined` rule noted above, in 2.x if such a method exists when the element is created, it will run with initial values of arguments, even in the case some or all arguments are `undefined`.
 * <a name="breaking-binding-notifications">‘notify’ events are no longer fired when value changes _as result of binding from host_, as a major performance optimization over 1.x behavior.  Use cases such as `<my-el foo="{{bar}}" on-foo-changed="fooChanged">` are no longer supported.  In this case you should simply user a `bar` observer in the host.  Use cases such as dynamically adding a `property-changed` event listener on for properties bound by an element's host by an actor other than the host are no longer supported.
-* <a name="breaking-properties-deserialization"></a>In order for a property to be deserialized from its attribute, it must be declared in the `properties` metadata object
+* <a name="breaking-properties-deserialization"></a>In order for a property to be deserialized from its attribute, it must be declared in the `properties` metadata object.
 * <a name="breaking-collection"></a>The `Polymer.Collection` and associated key-based path and splice notification for arrays has been eliminated.  See [explanation here](https://github.com/Polymer/polymer/pull/3970#issue-178203286) for more details.
 * <a name="feature-mutable-data"></a>While not a breaking change, Polymer now ships with a `Polymer.MutableData` mixin (and legacy `Polymer.MutableDataBehavior` behavior) to provide more options for managing data.  By default, `Polymer.PropertyEffects` performs strict dirty checking on objects, which means that any deep modifications to an object or array will not be propagated unless "immutable" data patterns are used (i.e. all object references from the root to the mutation were changed).  Polymer also provides a proprietary data mutation and path notification API (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient mutation and notification of deep changes in an object graph to all elements bound to the same object graph. In cases where neither immutable patterns or the data mutation API can be used, applying this mixin will cause Polymer to skip dirty checking for objects and arrays and always consider them to be "dirty".  This allows a user to make a deep modification to a bound object graph, and then either simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath` (e.g. `this.notifyPath('items')`) to update the tree.  Note that all elements that wish to be updated based on deep mutations must apply this mixin or otherwise skip strict dirty checking for objects/arrays.