From 834880368115ecade154b3a090e06159667c0c2d Mon Sep 17 00:00:00 2001
From: Julie <ju.ralph@gmail.com>
Date: Thu, 23 Jan 2014 11:56:27 -0800
Subject: [PATCH] docs(element): add in-code documentation for methods on
 element

---
 lib/protractor.js | 76 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/lib/protractor.js b/lib/protractor.js
index 9efbba248..e53d649cd 100644
--- a/lib/protractor.js
+++ b/lib/protractor.js
@@ -62,6 +62,20 @@ var buildElementHelper = function(ptor, opt_usingChain) {
     return base;
   }
 
+  /**
+   * The element function returns an Element Finder. Element Finders do
+   * not actually attempt to find the element until a method is called on them,
+   * which means they can be set up in helper files before the page is
+   * available.
+   *
+   * Example:
+   *     var nameInput = element(by.model('name'));
+   *     browser.get('myurl');
+   *     nameInput.sendKeys('Jane Doe');
+   *
+   * @param {webdriver.Locator} locator
+   * @return {ElementFinder}
+   */
   var element = function(locator) {
     var elementFinder = {};
 
@@ -85,17 +99,46 @@ var buildElementHelper = function(ptor, opt_usingChain) {
       return using().findElement(locator).findElement(subLocator);
     };
 
+    /**
+     * Return the actual WebElement.
+     *
+     * @return {webdriver.WebElement}
+     */
     elementFinder.find = function() {
       return using().findElement(locator);
     };
 
+    /**
+     * @return {boolean} whether the element is present on the page.
+     */
     elementFinder.isPresent = function() {
       return using().isElementPresent(locator);
     };
 
+    /**
+     * Calls to element may be chained to find elements within a parent.
+     * Example:
+     *     var name = element(by.id('container')).element(by.model('name'));
+     *     browser.get('myurl');
+     *     name.sendKeys('John Smith');
+     *
+     * @param {Protractor} ptor
+     * @param {=Array.<webdriver.Locator>} opt_usingChain
+     * @return {function(webdriver.Locator): ElementFinder}
+     */
     elementFinder.element =
         buildElementHelper(ptor, usingChain.concat(locator));
 
+    /**
+     * Shortcut for chaining css element finders.
+     * Example:
+     *     var name = element(by.id('container')).$('input.myclass');
+     *     browser.get('myurl');
+     *     name.sendKeys('John Smith');
+     *
+     * @param {string} cssSelector
+     * @return {ElementFinder}
+     */
     elementFinder.$ = function(cssSelector) {
       return buildElementHelper(ptor, usingChain.concat(locator))(
           webdriver.By.css(cssSelector));
@@ -105,17 +148,33 @@ var buildElementHelper = function(ptor, opt_usingChain) {
   };
 
   /**
-   * @type {function(webdriver.Locator): ElementArrayFinder}
+   * element.all is used for operations on an array of elements (as opposed
+   * to a single element).
+   *
+   * Example:
+   *     var lis = element.all(by.css('li'));
+   *     browser.get('myurl');
+   *     expect(lis.count()).toEqual(4);
+   *
+   * @param {webdriver.Locator} locator
+   * @return {ElementArrayFinder}
    */
   element.all = function(locator) {
     var elementArrayFinder = {};
 
+    /**
+     * @return {number} the number of elements matching the locator.
+     */
     elementArrayFinder.count = function() {
       return using().findElements(locator).then(function(arr) {
         return arr.length;
       });
     };
 
+    /**
+     * @param {number} index
+     * @return {webdriver.WebElement} the element at the given index
+     */
     elementArrayFinder.get = function(index) {
       var id = using().findElements(locator).then(function(arr) {
         return arr[index];
@@ -123,6 +182,9 @@ var buildElementHelper = function(ptor, opt_usingChain) {
       return ptor.wrapWebElement(new webdriver.WebElement(ptor.driver, id));
     };
 
+    /**
+     * @return {webdriver.WebElement} the first matching element
+     */
     elementArrayFinder.first = function() {
       var id = using().findElements(locator).then(function(arr) {
         if (!arr.length) {
@@ -133,6 +195,9 @@ var buildElementHelper = function(ptor, opt_usingChain) {
       return ptor.wrapWebElement(new webdriver.WebElement(ptor.driver, id));
     };
 
+    /**
+     * @return {webdriver.WebElement} the last matching element
+     */
     elementArrayFinder.last = function() {
       var id = using().findElements(locator).then(function(arr) {
         return arr[arr.length - 1];
@@ -140,10 +205,19 @@ var buildElementHelper = function(ptor, opt_usingChain) {
       return ptor.wrapWebElement(new webdriver.WebElement(ptor.driver, id));
     };
 
+    /**
+     * @type {webdriver.promise.Promise} a promise which will resolve to
+     *     an array of WebElements matching the locator.
+     */
     elementArrayFinder.then = function(fn) {
       return using().findElements(locator).then(fn);
     };
 
+    /**
+     * Calls the input function on each WebElement found by the locator.
+     *
+     * @param {function(webdriver.WebElement)}
+     */
     elementArrayFinder.each = function(fn) {
       using().findElements(locator).then(function(arr) {
         arr.forEach(function(webElem) {