changed the description of waitUntil command

lib/api/web-element/waitUntil.js

@@ -16,6 +16,56 @@ const mapToSeleniumFunction = {
   'not.present': (webElement, scopedElementLocator) => new Condition('until elmenet is not present', (driver) => driver.findElements(scopedElementLocator.condition).then(elements => elements.length ? false : true))
 };
 
+/**
+ * Waits a given time in milliseconds (default 5000ms) for an element to be in the action state provided before performing any other commands or assertions.
+ * If the element fails to be in the action state withing the given time, the test fails. You can change this by setting `abortOnFailure` to `false`.
+ *
+ * You can change the polling interval by defining a `waitForConditionPollInterval` property (in milliseconds) in as a global property in your `nightwatch.conf.js` or in your external globals file.
+ * Similarly, the default timeout can be specified as a global `waitForConditionTimeout` property (in milliseconds).
+ *
+ * @example
+ *  describe('demo Test', function() {
+ *   it ('wait for container', async function(browser){
+ *     // with default implicit timeout of 5000ms (can be overwritten in settings under 'globals.waitForConditionTimeout')
+ *     await browser.element.find('#index-container').waitUntil('visible');
+ *
+ *     // with explicit timeout (in milliseconds)
+ *     await browser.element.find('#index-container').waitUntil('visible', {timeout: 1000});
+ *
+ *     // continue if failed
+ *     await browser.element.find('#index-container').waitUntil('visible', {timeout: 1000, abortOnFailure: false});
+ *
+ *     // with negative assertion
+ *     await browser.element.find('#index-container').waitUntil('not.visible');
+ *
+ *     // with xpath as the locate strategy
+ *     await browser.element.find(by.xpath('//*[@id="index-container"]')).waitUntil('visible', {message: 'The index container is found.'});
+ *
+ *     // with custom message
+ *     await browser.element.find('#index-container').waitUntil('visible', {message: 'The index container is found.'});
+ *   });
+ *
+ *
+ *   it('page object demo Test', async function (browser) {
+ *     const nightwatchPage = browser.page.nightwatch();
+ *
+ *     nightwatchPage
+ *       .navigate()
+ *       .assert.titleContains('Nightwatch.js');
+ *
+ *     await nightwatchPage.element.find('@featuresList').waitUntil('visible');
+ *   });
+ * });
+ *
+ * @method waitUntil
+ * @syntax .waitUntil(action, {timeout, retryInterval, message, abortOnFailure});
+ * @param {string} action The action to perform. Can be one of the following: selected, not.selected, visible, not.visible, enabled, disabled, present, not.present
+ * @param {number} [timeout] The total number of milliseconds to wait before failing. Can also be set using 'globals.waitForConditionTimeout' under settings.
+ * @param {number} [retryInterval] The number of milliseconds to wait between retries. You can use this only if you also specify the time parameter. Can also be set using 'globals.waitForConditionPollInterval' under settings.
+ * @param {string} [message] Optional message to be shown in the output. The message supports two placeholders: %s for current selector and %d for the time (e.g. Element %s was not in the page for %d ms).
+ * @param {boolean} [abortOnFailure=abortOnAssertionFailure] By the default if the element is not found the test will fail. Set this to false if you wish for the test to continue even if the assertion fails. To set this globally you can define a property `abortOnAssertionFailure` in your globals.
+ */
+
 class WaitUntil {
   constructor(scopedElement, {action, timeout, retryInterval, message, nightwatchInstance, selector, abortOnFailure}) {
     this.scopedElement = scopedElement;