add some description of the dir mixin

dfreedm · dfreedm · commit f98ad11705d5 · 2017-10-11T11:04:52.000-07:00
diff --git a/lib/mixins/dir-mixin.html b/lib/mixins/dir-mixin.html
@@ -43,7 +43,19 @@
     }
 
     /**
-     * Some stuff about :dir
+     * Element class mixin that allows elements to use the `:dir` CSS Selector to have
+     * text direction specific styling.
+     *
+     * With this mixin, any stylesheet provided in the template will be transform `:dir` into
+     * `:host([dir])` and sync direction with the page via the element's `dir` attribute.
+     *
+     * Elements can opt out of the global page text direction by setting the `dir` attribute
+     * directly in `ready()`.
+     *
+     * Caveats:
+     * - Automatic left-to-right or right-to-left styling is sync'd with the `<html>` element
+     * - Applications must set `<html dir="ltr">` or `<html dir="rtl">` to sync direction
+     * - Opting out of the global direction styling is permanent
      *
      * @mixinFunction
      * @polymer
