docs(website): Improve documentation around drag and drop. (#3867)

Fixes #1205  Also adds support for `@external` to our docs.

Author: heathkit

Diff for: docs/faq.md

@@ -51,6 +51,13 @@ This is a [webdriver quirk](http://grokbase.com/t/gg/webdriver/12bcmvwhcm/extarc
 `<input>` and `<textarea>` elements always have
 empty `getText` values. Instead, try `element.getAttribute('value')`.
 
+How can I drag and drop elements?
+---------------------------------
+You can specify a sequence of [actions](http://www.protractortest.org/#/api?view=webdriver.WebDriver.prototype.actions)
+to drag an drop elements.  Note mouse actions do not work on Chrome with the HTML5 Drag and Drop API due to a known
+[Chromedriver issue](https://bugs.chromium.org/p/chromedriver/issues/detail?id=841)
+
+
 How can I interact directly with the JavaScript running in my app?
 ------------------------------------------------------------------
 

Diff for: lib/selenium-webdriver/webdriver.js

@@ -7,6 +7,20 @@
 
 goog.provide('webdriver');
 
+/**
+ * Class for defining sequences of complex user interactions.
+ * @external webdriver.ActionSequence
+ * @see http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/actions_exports_ActionSequence.html
+ */
+webdriver.ActionSequence = function() {};
+
+/**
+ * Class for defining sequences of user touch interactions.
+ * @external webdriver.TouchSequence
+ * @see http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_TouchSequence.html
+ */
+webdriver.TouchSequence = function() {};
+
 // //////////////////////////////////////////////////////////////////////////////
 // //
 // //  webdriver.WebDriver
@@ -25,20 +39,37 @@ goog.provide('webdriver');
 webdriver.WebDriver = function() {};
 
 /**
- * Creates a new action sequence using this driver. The sequence will not be
+ * Creates a sequence of user actions using this driver. The sequence will not be
  * scheduled for execution until {@link webdriver.ActionSequence#perform} is
  * called.
  *
- * See http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/actions_exports_ActionSequence.html
- * for more examples of action sequences.
+ * See the selenium webdriver docs <a href="http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/actions_exports_ActionSequence.html">
+ * for more details on action sequences</a>.
+ *
+ * Mouse actions do not work on Chrome with the HTML5 Drag and Drop API due to a known <a href="https://bugs.chromium.org/p/chromedriver/issues/detail?id=841">
+ *   Chromedriver issue</a>
  *
  * @example
+ * // Dragging one element to another.
  * browser.actions().
  *     mouseDown(element1).
  *     mouseMove(element2).
  *     mouseUp().
  *     perform();
  *
+ * // You can also use the `dragAndDrop` convenience action.
+ * browser.actions().
+ *     dragAndDrop(element1, element2).
+ *     perform();
+ *
+ * // Instead of specifying an element as the target, you can specify an offset
+ * // in pixels. This example double-clicks slightly to the right of an element.
+ * browser.actions().
+ *     mouseMove(element).
+ *     mouseMove({x: 50, y: 0}).
+ *     doubleClick().
+ *     perform();
+ *
  * @returns {!webdriver.ActionSequence} A new action sequence for this instance.
  */
 webdriver.WebDriver.prototype.actions = function() {};
@@ -48,13 +79,16 @@ webdriver.WebDriver.prototype.actions = function() {};
  * scheduled for execution until {@link actions.TouchSequence#perform} is
  * called.
  *
+ * See the selenium webdriver docs <a href="http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_TouchSequence.html">
+ * for more details on touch sequences</a>.
+ *
  * @example
  * browser.touchActions().
  *     tap(element1).
  *     doubleTap(element2).
  *     perform();
  *
- * @return {!actions.TouchSequence} A new touch sequence for this instance.
+ * @return {!webdriver.TouchSequence} A new touch sequence for this instance.
  */
 webdriver.WebDriver.prototype.touchActions = function() {};
 

Diff for: website/docgen/dgeni-config.js

@@ -14,6 +14,7 @@ jsDocProcessor.config(function(parseTagsProcessor) {
   tagDefs.push({name: 'deprecated'});
   tagDefs.push({name: 'example'});
   tagDefs.push({name: 'extends'});
+  tagDefs.push({name: 'external'});
   tagDefs.push({name: 'private'});
   tagDefs.push({name: 'type'});
   tagDefs.push({name: 'view'});

Diff for: website/docgen/processors/add-links.js

@@ -6,6 +6,12 @@ var _ = require('lodash');
  */
 var typeTable;
 
+/**
+ * A lookup table with links to external types.
+ * @type {Object.<string, string}
+ */
+var externalTypes = {};
+
 /**
  * The hash used to generate the links to the source code.
  */
@@ -88,6 +94,10 @@ var toMarkdownLinkFormat = function(link, doc, code) {
   }
   desc = desc.replace(new RegExp('\n', 'g'), ' ');
 
+  if (desc in externalTypes) {
+    type = externalTypes[desc];
+  }
+
   if (!type.match(/^https?:\/\//)) {
     // Remove extra '()' at the end of types
     if (type.substr(-2) == '()') {
@@ -144,6 +154,22 @@ var getTypeString = function(param) {
   return escape(str);
 };
 
+/**
+ * Filters out types with @external annotations and adds their @see link to the
+ * externalTypes table
+ *
+ * @param {Array.<Object>} docs The jsdoc list.
+ */
+var filterExternalDocs = function(docs) {
+  return _.reject(docs, function (doc) {
+    if (!!doc.external) {
+      externalTypes[doc.name] = doc.see[0];
+      return true;
+    }
+    return false;
+  });
+};
+
 /**
  * Add links to the external documents
  */
@@ -154,6 +180,8 @@ module.exports = function addLinks() {
     $process: function(docs) {
       typeTable = _.groupBy(docs, 'name');
 
+      docs = filterExternalDocs(docs);
+
       docs.forEach(function(doc) {
         addLinkToSourceCode(doc);
         doc.description = addLinkToLinkAnnotation(doc.description, doc);
@@ -173,6 +201,8 @@ module.exports = function addLinks() {
           doc.returnString = '';
         }
       });
+
+      return docs;
     }
   };
 };

Diff for: website/docgen/spec/add-links-spec.js

@@ -167,6 +167,46 @@ describe('add-links', function() {
         toBe('A promise located [{@code webdriver.WebElement}](webdriver.WebElement)s.');
   });
 
+  it('should add @external links', function() {
+    // Given a doc with a @external annotation.
+    var docs = [
+      {
+        name: 'webdriver.ActionSequence',
+        external: 'webdriver.ActionSequence',
+        see: [ 'http://seleniumhq.github.io/selenium/doc' ],
+      },
+      {
+        name: 'browser.action()',
+        description: 'Creates a new action sequence using the driver.',
+        fileName: 'protractor',
+        fileInfo: {filePath: ''},
+        startingLine: 3,
+        returns: {
+          tagDef: {
+            name: 'returns',
+            aliases: ['return'],
+            canHaveType: true
+          },
+          tagName: 'return',
+          description: 'A new action sequence for this instance.',
+          startingLine: 119,
+          typeExpression: 'webdriver.ActionSequence',
+          type: {
+            type: 'NameExpression',
+            name: 'webdriver.ActionSequence'
+          },
+          typeList: ['webdriver.ActionSequence']
+        }
+      }
+    ];
+
+    // When you add links.
+    addLinks(docs);
+
+    // Then ensure a link was added to the type.
+    expect(docs[1].returnString).toBe('[webdriver.ActionSequence](http://seleniumhq.github.io/selenium/doc)');
+  });
+
   it('should handle {@link type desc} links', function() {
     // Given a doc with a @link annotation.
     var docs = [

Diff for: website/test/e2e/api_spec.js

@@ -104,7 +104,7 @@ describe('Api', function() {
 
     // Then ensure the child functions are shown.
     expect(apiPage.getChildFunctionNames()).toEqual([
-      'then', 'clone', 'locator', 'getWebElement', 'all', 'element', '$$',
+      'clone', 'locator', 'getWebElement', 'all', 'element', '$$',
       '$', 'isPresent', 'isElementPresent', 'evaluate', 'allowAnimations', 'equals']);
   });