Improve documentation and legibility.

- Did a pass for every place we were writing `Polymer.foo`.
- Basic cleanup of a number of places for legibility by both humans and polymer-analyzer.

lib/elements/array-selector.js

@@ -29,8 +29,7 @@ import { ElementMixin } from '../mixins/element-mixin.js';
  *
  * @polymer
  * @mixinFunction
- * @appliesMixin Polymer.ElementMixin
- * @memberof Polymer
+ * @appliesMixin ElementMixin
  * @summary Element mixin for recording dynamic associations between item paths in a
  * master `items` array and a `selected` array
  */
@@ -342,13 +341,13 @@ export { ArraySelectorMixin };
 
 /**
  * @constructor
- * @extends {Polymer.Element}
+ * @extends {PolymerElement}
  * @implements {Polymer_ArraySelectorMixin}
  */
 let baseArraySelector = ArraySelectorMixin(PolymerElement);
 
 /**
- * Element implementing the `Polymer.ArraySelector` mixin, which records
+ * Element implementing the `ArraySelector` mixin, which records
  * dynamic associations between item paths in a master `items` array and a
  * `selected` array such that path changes to the master array (at the host)
  * element or elsewhere via data-binding) are correctly propagated to items
@@ -364,63 +363,60 @@ let baseArraySelector = ArraySelectorMixin(PolymerElement);
  *
  * Example:
  *
- * ```html
- * <dom-module id="employee-list">
- *
- *   <template>
- *
- *     <div> Employee list: </div>
- *     <dom-repeat id="employeeList" items="{{employees}}">
- *       <template>
- *         <div>First name: <span>{{item.first}}</span></div>
- *           <div>Last name: <span>{{item.last}}</span></div>
- *           <button on-click="toggleSelection">Select</button>
- *       </template>
- *     </dom-repeat>
- *
- *     <array-selector id="selector" items="{{employees}}" selected="{{selected}}" multi toggle></array-selector>
- *
- *     <div> Selected employees: </div>
- *     <dom-repeat items="{{selected}}">
- *       <template>
- *         <div>First name: <span>{{item.first}}</span></div>
- *         <div>Last name: <span>{{item.last}}</span></div>
- *       </template>
- *     </dom-repeat>
+ * ```js
+ * import {PolymerElement} from '@polymer/polymer';
+ * import '@polymer/polymer/lib/elements/array-selector.js';
  *
- *   </template>
+ * class EmployeeList extends PolymerElement {
+ *   static get _template() {
+ *     return html`
+ *         <div> Employee list: </div>
+ *         <dom-repeat id="employeeList" items="{{employees}}">
+ *           <template>
+ *             <div>First name: <span>{{item.first}}</span></div>
+ *               <div>Last name: <span>{{item.last}}</span></div>
+ *               <button on-click="toggleSelection">Select</button>
+ *           </template>
+ *         </dom-repeat>
  *
- * </dom-module>
- * ```
+ *         <array-selector id="selector"
+ *                         items="{{employees}}"
+ *                         selected="{{selected}}"
+ *                         multi toggle></array-selector>
  *
- * ```js
- *class EmployeeList extends Polymer.Element {
- *  static get is() { return 'employee-list'; }
- *  static get properties() {
- *    return {
- *      employees: {
- *        value() {
- *          return [
- *            {first: 'Bob', last: 'Smith'},
- *            {first: 'Sally', last: 'Johnson'},
- *            ...
- *          ];
- *        }
- *      }
- *    };
- *  }
- *  toggleSelection(e) {
- *    let item = this.$.employeeList.itemForElement(e.target);
- *    this.$.selector.select(item);
- *  }
- *}
+ *         <div> Selected employees: </div>
+ *         <dom-repeat items="{{selected}}">
+ *           <template>
+ *             <div>First name: <span>{{item.first}}</span></div>
+ *             <div>Last name: <span>{{item.last}}</span></div>
+ *           </template>
+ *         </dom-repeat>`;
+ *   }
+ *   static get is() { return 'employee-list'; }
+ *   static get properties() {
+ *     return {
+ *       employees: {
+ *         value() {
+ *           return [
+ *             {first: 'Bob', last: 'Smith'},
+ *             {first: 'Sally', last: 'Johnson'},
+ *             ...
+ *           ];
+ *         }
+ *       }
+ *     };
+ *   }
+ *   toggleSelection(e) {
+ *     const item = this.$.employeeList.itemForElement(e.target);
+ *     this.$.selector.select(item);
+ *   }
+ * }
  * ```
  *
  * @polymer
  * @customElement
  * @extends {baseArraySelector}
- * @appliesMixin Polymer.ArraySelectorMixin
- * @memberof Polymer
+ * @appliesMixin ArraySelectorMixin
  * @summary Custom element that links paths between an input `items` array and
  *   an output `selected` item or array based on calls to its selection API.
  */

lib/elements/custom-style.js

@@ -58,11 +58,10 @@ const CustomStyleInterface = window.ShadyCSS.CustomStyleInterface;
  *
  * @customElement
  * @extends HTMLElement
- * @memberof Polymer
  * @summary Custom element for defining styles in the main document that can
  *   take advantage of Polymer's style scoping and custom properties shims.
  */
-class CustomStyle extends HTMLElement {
+export class CustomStyle extends HTMLElement {
   constructor() {
     super();
     this._style = null;
@@ -107,4 +106,3 @@ class CustomStyle extends HTMLElement {
 }
 
 window.customElements.define('custom-style', CustomStyle);
-export { CustomStyle };

lib/elements/dom-bind.js

@@ -37,15 +37,14 @@ const domBindBase =
  *
  * @polymer
  * @customElement
- * @appliesMixin Polymer.PropertyEffects
- * @appliesMixin Polymer.OptionalMutableData
- * @appliesMixin Polymer.GestureEventListeners
+ * @appliesMixin PropertyEffects
+ * @appliesMixin OptionalMutableData
+ * @appliesMixin GestureEventListeners
  * @extends {domBindBase}
- * @memberof Polymer
  * @summary Custom element to allow using Polymer's template features (data
  *   binding, declarative event listeners, etc.) in the main document.
  */
-class DomBind extends domBindBase {
+export class DomBind extends domBindBase {
 
   static get observedAttributes() { return ['mutable-data']; }
 
@@ -126,5 +125,3 @@ class DomBind extends domBindBase {
 }
 
 customElements.define('dom-bind', DomBind);
-
-export { DomBind };

lib/elements/dom-if.js

@@ -32,12 +32,11 @@ import { root as root$0 } from '../utils/path.js';
  *
  * @customElement
  * @polymer
- * @extends Polymer.Element
- * @memberof Polymer
+ * @extends PolymerElement
  * @summary Custom element that conditionally stamps and hides or removes
  *   template content based on a boolean flag.
  */
-class DomIf extends PolymerElement {
+export class DomIf extends PolymerElement {
 
   // Not needed to find template; can be removed once the analyzer
   // can find the tag name from customElements.define call
@@ -278,5 +277,3 @@ class DomIf extends PolymerElement {
 }
 
 customElements.define(DomIf.is, DomIf);
-
-export { DomIf };

lib/elements/dom-module.js

@@ -44,12 +44,11 @@ function styleOutsideTemplateCheck(inst) {
  *
  * @customElement
  * @extends HTMLElement
- * @memberof Polymer
  * @summary Custom element that provides a registry of relocatable DOM content
  *   by `id` that is agnostic to bundling.
  * @unrestricted
  */
-class DomModule extends HTMLElement {
+export class DomModule extends HTMLElement {
 
   static get observedAttributes() { return ['id']; }
 
@@ -136,6 +135,3 @@ class DomModule extends HTMLElement {
 DomModule.prototype['modules'] = modules;
 
 customElements.define('dom-module', DomModule);
-
-// export
-export { DomModule };

lib/elements/dom-repeat.js

@@ -21,7 +21,7 @@ let TemplateInstanceBase = TemplateInstanceBase$0; // eslint-disable-line
 /**
  * @constructor
  * @implements {Polymer_OptionalMutableData}
- * @extends {Polymer.Element}
+ * @extends {PolymerElement}
  */
 const domRepeatBase = OptionalMutableData(PolymerElement);
 
@@ -56,7 +56,7 @@ const domRepeatBase = OptionalMutableData(PolymerElement);
  * With the following custom element definition:
  *
  * ```js
- * class EmployeeList extends Polymer.Element {
+ * class EmployeeList extends PolymerElement {
  *   static get is() { return 'employee-list'; }
  *   static get properties() {
  *     return {
@@ -78,15 +78,14 @@ const domRepeatBase = OptionalMutableData(PolymerElement);
  * instances, which will update via the normal structured data notification system.
  *
  * Mutations to the `items` array itself should be made using the Array
- * mutation API's on `Polymer.Base` (`push`, `pop`, `splice`, `shift`,
- * `unshift`), and template instances will be kept in sync with the data in the
- * array.
+ * mutation API's on the PropertyEffects mixin (`push`, `pop`, `splice`,
+ * `shift`, `unshift`), and template instances will be kept in sync with the
+ * data in the array.
  *
  * Events caught by event handlers within the `dom-repeat` template will be
  * decorated with a `model` property, which represents the binding scope for
- * each template instance.  The model is an instance of Polymer.Base, and should
- * be used to manipulate data on the instance, for example
- * `event.model.set('item.checked', true);`.
+ * each template instance.  The model should be used to manipulate data on the
+ * instance, for example `event.model.set('item.checked', true);`.
  *
  * Alternatively, the model for a template instance for an element stamped by
  * a `dom-repeat` can be obtained using the `modelForElement` API on the
@@ -123,13 +122,12 @@ const domRepeatBase = OptionalMutableData(PolymerElement);
  *
  * @customElement
  * @polymer
- * @memberof Polymer
  * @extends {domRepeatBase}
- * @appliesMixin Polymer.OptionalMutableData
+ * @appliesMixin OptionalMutableData
  * @summary Custom element for stamping instance of a template bound to
  *   items in an array.
  */
-class DomRepeat extends domRepeatBase {
+export class DomRepeat extends domRepeatBase {
 
   // Not needed to find template; can be removed once the analyzer
   // can find the tag name from customElements.define call
@@ -707,7 +705,7 @@ class DomRepeat extends domRepeatBase {
   /**
    * Returns the template "model" associated with a given element, which
    * serves as the binding scope for the template instance the element is
-   * contained in. A template model is an instance of `Polymer.Base`, and
+   * contained in. A template model
    * should be used to manipulate data associated with this template instance.
    *
    * Example:
@@ -728,5 +726,3 @@ class DomRepeat extends domRepeatBase {
 }
 
 customElements.define(DomRepeat.is, DomRepeat);
-
-export { DomRepeat };

lib/legacy/class.js

@@ -26,19 +26,19 @@ let metaProps = {
 /**
  * Applies a "legacy" behavior or array of behaviors to the provided class.
  *
- * Note: this method will automatically also apply the `Polymer.LegacyElementMixin`
+ * Note: this method will automatically also apply the `LegacyElementMixin`
  * to ensure that any legacy behaviors can rely on legacy Polymer API on
  * the underlying element.
  *
+ * @function
  * @template T
  * @param {!Object|!Array<!Object>} behaviors Behavior object or array of behaviors.
  * @param {function(new:T)} klass Element class.
  * @return {function(new:T)} Returns a new Element class extended by the
- * passed in `behaviors` and also by `Polymer.LegacyElementMixin`.
- * @memberof Polymer
+ * passed in `behaviors` and also by `LegacyElementMixin`.
  * @suppress {invalidCasts, checkTypes}
  */
-function mixinBehaviors(behaviors, klass) {
+export function mixinBehaviors(behaviors, klass) {
   if (!behaviors) {
     klass = /** @type {HTMLElement} */(klass); // eslint-disable-line no-self-assign
     return klass;
@@ -85,7 +85,7 @@ function mixinBehaviors(behaviors, klass) {
 // element's prototype chain. Behaviors are placed in the element prototype
 // eldest to youngest and de-duped youngest to oldest:
 // So, first [A, B, C, A, B] becomes [C, A, B] then,
-// the element prototype becomes (oldest) (1) Polymer.Element, (2) class(C),
+// the element prototype becomes (oldest) (1) PolymerElement, (2) class(C),
 // (3) class(A), (4) class(B), (5) class(Polymer({...})).
 // Result:
 // This means element properties win over B properties win over A win
@@ -286,7 +286,7 @@ function GenerateClassFromInfo(info, Base) {
 }
 
 /**
- * Generates a class that extends `Polymer.LegacyElement` based on the
+ * Generates a class that extends `LegacyElement` based on the
  * provided info object.  Metadata objects on the `info` object
  * (`properties`, `observers`, `listeners`, `behaviors`, `is`) are used
  * for Polymer's meta-programming systems, and any functions are copied
@@ -354,7 +354,7 @@ function GenerateClassFromInfo(info, Base) {
  */
 export const Class = function(info) {
   if (!info) {
-    console.warn('Polymer.Class requires `info` argument');
+    console.warn(`Polymer's Class function requires \`info\` argument`);
   }
   let klass = GenerateClassFromInfo(info, info.behaviors ?
     // note: mixinBehaviors ensures `LegacyElementMixin`.
@@ -364,5 +364,3 @@ export const Class = function(info) {
   klass.is = info.is;
   return klass;
 };
-
-export { mixinBehaviors };

lib/legacy/polymer-fn.js

@@ -16,13 +16,15 @@ import '../utils/boot.js';
  * elements.
  *
  * This method is equivalent to
- * `customElements.define(info.is, Polymer.Class(info));`
  *
- * See `Polymer.Class` for details on valid legacy metadata format for `info`.
+ *     import {Class} from '@polymer/polymer/lib/legacy/class.js';
+ *     customElements.define(info.is, Class(info));
+ *
+ * See `Class` for details on valid legacy metadata format for `info`.
  *
  * @global
  * @override
- * @function Polymer
+ * @function
  * @param {!PolymerInit} info Object containing Polymer metadata and functions
  *   to become class methods.
  * @return {function(new: HTMLElement)} Generated class