diff --git a/src/lib/template/dom-repeat.html b/src/lib/template/dom-repeat.html
index 63c548a328..5e3fc46f92 100644
--- a/src/lib/template/dom-repeat.html
+++ b/src/lib/template/dom-repeat.html
@@ -69,14 +69,25 @@
 This may be useful for manipulating instance data of event targets obtained
 by event handlers on parents of the `dom-repeat` (event delegation).
 
-A view-specific filter/sort may be applied to each `dom-repeat` by supplying a
-`filter` and/or `sort` property.  This may be a string that names a function on
-the host, or a function may be assigned to the property directly.  The functions
-should implemented following the standard `Array` filter/sort API.
-
-In order to re-run the filter or sort functions based on changes to sub-fields
-of `items`, the `observe` property may be set as a space-separated list of
-`item` sub-fields that should cause a re-filter/sort when modified.  If
+To filter or sort the _displayed_ items in your list, specify a `filter` or
+`sort` property on the `dom-repeat` (or both):
+
+*   `filter`. Specifies a filter callback function, that takes a single argument
+    (the item) and returns true to display the item, false to omit it.
+    (Note that this is **similar** to the standard
+    `Array` [`filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) API, but the callback only takes a single argument.)
+*   `sort`. Specifies a comparison function following the standard `Array`
+    [`sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) API.
+
+In both cases, the value can be either a function object, or a string identifying a
+function defined on the host element.
+
+By default, the `filter` and `sort` functions only run when the array itself
+is mutated (for example, by adding or removing items).
+
+To re-run the `filter` or `sort` functions when certain sub-fields
+of `items` change, set the `observe` property to a space-separated list of
+`item` sub-fields that should cause the list to be re-filtered or re-sorted. If
 the filter or sort function depends on properties not contained in `items`,
 the user should observe changes to those properties and call `render` to update
 the view based on the dependency change.
@@ -159,11 +170,12 @@
       },
 
       /**
-       * A function that can be used to filter items out of the view.  This
-       * property should either be provided as a string, indicating a method
-       * name on the element's host, or else be an actual function.  The
-       * function should match the sort function passed to `Array.filter`.
-       * Using a filter function has no effect on the underlying `items` array.
+       * `filter`. Specifies a filter callback function, that takes a single
+       * argument (the item) and returns true to display the item, false to omit
+       * it. Using a filter callback has no effect on the underlying `items`
+       * array.
+       * (Note that this is **similar** to the standard `Array`
+       * [`filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) API, but the callback only takes a single argument.)
        */
       filter: {
         type: Function,