From d2d9069bf7ebe319fbf4c758b35644d4f73afb34 Mon Sep 17 00:00:00 2001
From: Monica Dinculescu <noms@google.com>
Date: Tue, 6 Oct 2015 16:15:32 -0700
Subject: [PATCH] add docs for this thing

---
 iron-validatable-behavior.html | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/iron-validatable-behavior.html b/iron-validatable-behavior.html
index e790477..8060713 100644
--- a/iron-validatable-behavior.html
+++ b/iron-validatable-behavior.html
@@ -14,7 +14,20 @@
 <script>
 
   /**
-   * Use `Polymer.IronValidatableBehavior` to implement an element that validates user input.
+   * `Use Polymer.IronValidatableBehavior` to implement an element that validates user input.
+   * Use the related `Polymer.IronValidatorBehavior` to add custom validation logic to an iron-input.
+   *
+   * By default, an `<iron-form>` element validates its fields when the user presses the submit button.
+   * To validate a form imperatively, call the form's `validate()` method, which in turn will
+   * call `validate()` on all its children. By using `Polymer.IronValidatableBehavior`, your
+   * custom element will get a public `validate()`, which
+   * will return the validity of the element, and a corresponding `invalid` attribute,
+   * which can be used for styling.
+   *
+   * To implement the custom validation logic of your element, you must override
+   * the protected `_getValidity()` method of this behaviour, rather than `validate()`.
+   * See [this](https://github.com/PolymerElements/iron-form/blob/master/demo/simple-element.html)
+   * for an example.
    *
    * ### Accessibility
    *