diff --git a/lib/mixins/element-mixin.html b/lib/mixins/element-mixin.html
index 3f0483888f..73ffe10fb0 100644
--- a/lib/mixins/element-mixin.html
+++ b/lib/mixins/element-mixin.html
@@ -627,6 +627,10 @@
        * this element. This method will return the same URL before and after
        * bundling.
        *
+       * Note that this function performs no resolution for URLs that start
+       * with `/` (absolute URLs) or `#` (hash identifiers).  For general purpose
+       * URL resolution, use `window.URL`.
+       *
        * @param {string} url URL to resolve.
        * @param {string=} base Optional base URL to resolve against, defaults
        * to the element's `importPath`
diff --git a/lib/utils/resolve-url.html b/lib/utils/resolve-url.html
index 357ef6a322..6d061a826e 100644
--- a/lib/utils/resolve-url.html
+++ b/lib/utils/resolve-url.html
@@ -20,6 +20,10 @@
     let resolveDoc;
     /**
      * Resolves the given URL against the provided `baseUri'.
+     * 
+     * Note that this function performs no resolution for URLs that start
+     * with `/` (absolute URLs) or `#` (hash identifiers).  For general purpose
+     * URL resolution, use `window.URL`.
      *
      * @memberof Polymer.ResolveUrl
      * @param {string} url Input URL to resolve