Documentation on By.js is Incorrect

[machineghost]

🐛 Bug Report

In Javascript an expression (eg. 1 + 1) and a statement (eg. const a = 1 + 1; or return a;) are different things, but the documentation for By.js refers to it requiring an "expression" when it actually requires a statement (specifically a return statement).

To Reproduce

1. Go to https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/by_exports_By.html#By.js
2. Try to follow the instructions: provide a "a JavaScript expression"
3. Receive a (difficult to debug) TypeError: Custom locator did not return a WebElement
4. Change the "Javascript expression" to instead be the statement of: return *whatever expression you had before*
5. Get your expected element

Expected behavior

The documentation should be changed from:

Locates an elements by evaluating a JavaScript expression. The result of this expression must be an element or list of elements.

to:

Locates elements by evaluating a JavaScript return statement. The value returned from this statement must be an element or list of elements.

Example:
driver.findElement({ js: "return document.querySelectorAll('button')" }))

Arguably a much better solution would be to make this function actually expect an expression. There's really no reason to make devs provide:

return document.querySelector('foo')`

when they could just provide:

`document.querySelector('foo')`

... but I'm guessing it's easier to avoid breaking things by just fixing the documentation :)

OS: Any
Browser:Any
Browser version: Any
Browser Driver version: Current (documentation for version at https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/by_exports_By.html#By.js)
Language Bindings version: Javascript
Selenium Grid version (if applicable): n/a

[machineghost]

Thanks!