From e90ef30d79c4bce2d788caa8257d4181dafe3fdf Mon Sep 17 00:00:00 2001
From: Kevin Schaaf <kschaaf@google.com>
Date: Thu, 27 Apr 2017 16:17:36 -0700
Subject: [PATCH] Ensure tags in markdown are backtracked. Short-term stopgap
 to ensure they are not rendered in HTML.

---
 lib/legacy/legacy-element-mixin.html    |  2 +-
 lib/mixins/property-effects.html        |  4 ++--
 lib/mixins/template-stamp.html          | 29 +++++++++++++++----------
 lib/utils/flattened-nodes-observer.html |  6 ++---
 4 files changed, 23 insertions(+), 18 deletions(-)

diff --git a/lib/legacy/legacy-element-mixin.html b/lib/legacy/legacy-element-mixin.html
index e831d6c1ef..013d86efd8 100644
--- a/lib/legacy/legacy-element-mixin.html
+++ b/lib/legacy/legacy-element-mixin.html
@@ -430,7 +430,7 @@
        * are not automatically handled. For example,
        * a user should call `distributeContent` if distribution has been
        * invalidated due to an element being added or removed from the shadowRoot
-       * that contains an insertion point (<slot>) inside its subtree.
+       * that contains an insertion point (`<slot>`) inside its subtree.
        */
       distributeContent() {
         if (window.ShadyDOM && this.shadowRoot) {
diff --git a/lib/mixins/property-effects.html b/lib/mixins/property-effects.html
index 5be94f0c8f..2321826b7e 100644
--- a/lib/mixins/property-effects.html
+++ b/lib/mixins/property-effects.html
@@ -605,7 +605,7 @@
 
   /**
    * Returns true if a binding's metadata meets all the requirements to allow
-   * 2-way binding, and therefore a <property>-changed event listener should be
+   * 2-way binding, and therefore a `<property>-changed` event listener should be
    * added:
    * - used curly braces
    * - is a property (not attribute) binding
@@ -1322,7 +1322,7 @@
        *
        * The implementation makes a best-effort at binding interop:
        * Some native element properties have side-effects when
-       * re-setting the same value (e.g. setting <input>.value resets the
+       * re-setting the same value (e.g. setting `<input>.value` resets the
        * cursor position), so we do a dirty-check before setting the value.
        * However, for better interop with non-Polymer custom elements that
        * accept objects, we explicitly re-set object changes coming from the
diff --git a/lib/mixins/template-stamp.html b/lib/mixins/template-stamp.html
index af17ee3bfe..5efcab5303 100644
--- a/lib/mixins/template-stamp.html
+++ b/lib/mixins/template-stamp.html
@@ -136,43 +136,46 @@
        * The template metadata object returned from this method has the following
        * structure (many fields optional):
        *
+       * ```js
        *   {
        *     // Flattened list of node metadata (for nodes that generated metadata)
        *     nodeInfoList: [
        *       {
        *         // `id` attribute for any nodes with id's for generating `$` map
-       *         id: '<id>',
+       *         id: {string},
        *         // `on-event="handler"` metadata
        *         events: [
        *           {
-       *             name: '<name>'
-       *             value: '<handler name>'
+       *             name: {string},   // event name
+       *             value: {string},  // handler method name
        *           }, ...
        *         ],
        *         // Notes when the template contained a `<slot>` for shady DOM
        *         // optimization purposes
-       *         hasInsertionPoint: <boolean>,
-       *         // For nested <template> nodes, nested template metadata
-       *         templateInfo: <nested template metadata>,
+       *         hasInsertionPoint: {boolean},
+       *         // For nested `<template>`` nodes, nested template metadata
+       *         templateInfo: {object}, // nested template metadata
        *         // Metadata to allow efficient retrieval of instanced node
        *         // corresponding to this metadata
-       *         parentInfo: <reference to parent nodeInfo>,
-       *         parentIndex: <integer index in parent's `childNodes` collection>
-       *         infoIndex: <integer index of this `nodeInfo` in `templateInfo.nodeInfoList`
+       *         parentInfo: {number},   // reference to parent nodeInfo>
+       *         parentIndex: {number},  // index in parent's `childNodes` collection
+       *         infoIndex: {number},    // index of this `nodeInfo` in `templateInfo.nodeInfoList`
        *       },
        *       ...
        *     ],
        *     // When true, the template had the `strip-whitespace` attribute
        *     // or was nested in a template with that setting
-       *     stripWhitespace: <boolean>
+       *     stripWhitespace: {boolean},
        *     // For nested templates, nested template content is moved into
        *     // a document fragment stored here; this is an optimization to
        *     // avoid the cost of nested template cloning
-       *     content: <DocumentFragment>
+       *     content: {DocumentFragment}
        *   }
+       * ```
        *
        * This method kicks off a recursive treewalk as follows:
        *
+       * ```
        *    _parseTemplate <---------------------+
        *      _parseTemplateContent              |
        *        _parseTemplateNode  <------------|--+
@@ -181,6 +184,8 @@
        *          _parseTemplateNodeAttributes
        *            _parseTemplateNodeAttribute
        *
+       * ```
+       *
        * These methods may be overridden to add custom metadata about templates
        * to either `templateInfo` or `nodeInfo`.
        *
@@ -396,7 +401,7 @@
        *
        * Note that the memoized template parsing process is destructive to the
        * template: attributes for bindings and declarative event listeners are
-       * removed after being noted in notes, and any nested <template>.content
+       * removed after being noted in notes, and any nested `<template>.content`
        * is removed and stored in notes as well.
        *
        * @param {HTMLTemplateElement} template Template to stamp
diff --git a/lib/utils/flattened-nodes-observer.html b/lib/utils/flattened-nodes-observer.html
index c1f75d038b..66ad7795f7 100644
--- a/lib/utils/flattened-nodes-observer.html
+++ b/lib/utils/flattened-nodes-observer.html
@@ -21,7 +21,7 @@
   /**
    * Class that listens for changes (additions or removals) to
    * "flattened nodes" on a given `node`. The list of flattened nodes consists
-   * of a node's children and, for any children that are <slot> elements,
+   * of a node's children and, for any children that are `<slot>` elements,
    * the expanded flattened list of `assignedNodes`.
    * For example, if the observed node has children `<a></a><slot></slot><b></b>`
    * and the `<slot>` has one `<div>` assigned to it, then the flattened
@@ -35,7 +35,7 @@
    *
    * Note: the callback is called asynchronous to any changes
    * at a microtask checkpoint. This is because observation is performed using
-   * `MutationObserver` and the `<slot> element's `slotchange` event which
+   * `MutationObserver` and the `<slot>` element's `slotchange` event which
    * are asynchronous.
    *
    * @memberof Polymer
@@ -50,7 +50,7 @@
     /**
      * Returns the list of flattened nodes for the given `node`.
      * This list consists of a node's children and, for any children
-     * that are <slot> elements, the expanded flattened list of `assignedNodes`.
+     * that are `<slot>` elements, the expanded flattened list of `assignedNodes`.
      * For example, if the observed node has children `<a></a><slot></slot><b></b>`
      * and the `<slot>` has one `<div>` assigned to it, then the flattened
      * nodes list is `<a></a><div></div><b></b>`. If the `<slot>` has other