The webdriver/protractor split in docs API is confusing

[juliemr]

Users don't care that some functions are added by Protractor, and some are wrapped. It's confusing that locators, for example, live in two different locations. We should merge and present this more clearly.

[andresdominguez]

We need examples for all the locators. The webdriver jsdocs do not have examples. Probably we need special annotations to extend examples.

We can have an empty file that contains a bunch of annotations for examples. What about something like this:

/**
 * @extendsDoc {webdriver.By.linkText}
 * @replaceDoc
 * [optional] Text that will replace the original jsdoc.
 * @appendDoc
 * [optional] Text that will be appended to the original webdriver jsdoc
 * @view
 * <a>Julie</a>
 * <a>Hank</a>
 *
 * @example
 * expect(element(by.linkText('Julie')).isPresent()).toBe(true);
 */

[juliemr]

Assigning @sjelin as he's working on it.