From 8b4460cddda3704d47daed033d063e80663448fb Mon Sep 17 00:00:00 2001
From: spalger <email@spalger.com>
Date: Wed, 23 Sep 2015 11:51:35 -0700
Subject: [PATCH] [jquery/findTestSubject] clarified docs

---
 src/ui/public/jquery/findTestSubject.js | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/src/ui/public/jquery/findTestSubject.js b/src/ui/public/jquery/findTestSubject.js
index 6b9bc5e788f4..6ffb01789a9a 100644
--- a/src/ui/public/jquery/findTestSubject.js
+++ b/src/ui/public/jquery/findTestSubject.js
@@ -3,28 +3,30 @@ module.exports = function bindToJquery($) {
   /**
    * Find elements with the `data-test-subj` attribute by the terms in that attribute.
    *
-   * Find all of the element inside $el with the "saveButton" subject.
-   *
    * ```js
-   * var $button = $el.findTestSubject('saveButton');
+   * // this
+   * var $button = $('[data-test-subj~="saveButton"]');
+   *
+   * // becomes this
+   * var $button = $.findTestSubject('saveButton');
    * ```
    *
-   * Find all of the elements with either "saveButton" or "cancelButton"
-   *
+   * Supports multiple subjects
    * ```js
+   * // find any saveButton or cancelButton
    * var $buttons = $.findTestSubject('saveButton', 'cancelButton');
    * ```
    *
-   * Find all of the elements with a subject that decent from another subject
-   *
+   * Supports subject "selectors"
    * ```js
+   * // find any saveButton inside a savedObjectForm
    * var $button = $.findTestSubject('savedObjectForm saveButton');
    * ```
    *
-   * Find all of the elements which have both subjects
-   *
+   * Supports selecting compound subjects
    * ```js
-   * var $input = $.findTestSubject('smallButton&saveButton');
+   * // find any smallButton that is also a saveButton inside a savedObjectForm
+   * var $input = $.findTestSubject('savedObjectForm smallButton&saveButton');
    * ```
    *
    * @return {jQueryCollection}