updated page object documentation

Author: John Doherty

README.MD

@@ -114,33 +114,40 @@ An example page object:
 
 module.exports = {
 
+    url: 'http://www.google.co.uk',
+
     elements: {
-        searchInput: by.name('q')
+        searchInput: by.name('q'),
+        searchResultLink: by.css('div.g > h3 > a')
     },
 
-    preformSearch: function (keywords) {
+    /**
+     * enters a search term into Google's search box and presses enter
+     * @param {string} searchQuery
+     * @returns {Promise} a promise to enter the search values
+     */
+    preformSearch: function (searchQuery) {
 
-        // notice the element path below use the full page qualifier
-        var input = driver.findElement(page.googleSearch.elements.searchInput);
+        var selector = page.googleSearch.elements.searchInput;
 
-        input.sendKeys(keywords);
-        input.sendKeys(selenium.Key.ENTER);
+        // return a promise so the calling function knows the task has completed
+        return driver.findElement(selector).sendKeys(searchQuery, selenium.Key.ENTER);
     }
 };
 ```
 
 And its usage within a step definition:
 
 ```js
-module.exports = function () {
-
-    this.When(/^I search Google for "([^"]*)"$/, function (searchQuery, done) {
+// ./step-definitions/google-search-steps.js
+this.When(/^I search Google for "([^"]*)"$/, function (searchQuery) {
 
-        page.googleSearch.preformSearch(searchQuery);
+    return helpers.loadPage('http://www.google.com').then(function() {
 
-        done(); // <<- let cucumber know you're done
-    });
-};
+        // use a method on the page object which also returns a promise
+        return page.googleSearch.preformSearch(searchQuery);
+    })
+});
 ```
 
 ### Shared objects

page-objects/google-search.js

@@ -7,10 +7,16 @@ module.exports = {
         searchResultLink: by.css('div.g > h3 > a')
     },
 
-    preformSearch: function (keywords) {
+    /**
+     * enters a search term into Google's search box and presses enter
+     * @param {string} searchQuery
+     * @returns {Promise} a promise to enter the search values
+     */
+    preformSearch: function (searchQuery) {
 
         var selector = page.googleSearch.elements.searchInput;
 
-        return driver.findElement(selector).sendKeys(keywords, selenium.Key.ENTER);
+        // return a promise so the calling function knows the task has completed
+        return driver.findElement(selector).sendKeys(searchQuery, selenium.Key.ENTER);
     }
 };