Use Promise in example for #evaluate_async

[ttilberg]

Related to #234

I couldn't remember how to get a value back from evaluate_async and remembered I had created an example in a previous issue.

The existing example leverages arguments[0] and calls a simple object. Instead, I would like to see an actual, practical example using familiar things that people would commonly use this for.

Additionally, I think we should encourage usage of __f() as in the next example, instead of arguments[0], or rework the #evaluate_async template. As an example, if you call:

browser.evaluate_async '__f(arguments)', 5, "arg 1", 2, 3
# => ["arg 1", 2, 3, {}]

arguments[0] no longer refers to the fulfill callback. You end up receiving TypeError: arguments[0] is not a function (Ferrum::JavaScriptError).

Perhaps this highlights some tweaks that could be made to evaluate_async, but for now, I'd like to get this docs change up asap.

[route]

I don't like current API either, but I remember picking up the names for resolve and reject functions so that they don't collide with any other name (thus I added __), and now we are making them kinda explicit. Looking at:

browser.evaluate_async '__f(arguments)', 5, "arg 1", 2, 3

is so unreadable. I'm always confused when to put what, and use specs to remember how to use it. So maybe it's time to improve the API then if it's doable at all? :)

[alexeyr-ci]

Reminding about this PR because I just also was confused by arguments[0] in the README.

[ttilberg]

I ended up here to reference the __r trick again. @route I noticed you have a new issue from Jan for planning a 1.0 release that may include this type of change. I was thinking today "what if the resolve argument was called resolveToFerrum" or something. Putting ferrum in the name would help isolation as you wanted, but keep meaningful language that helps people connect the dots. Just wanted to put the thought forward for consideration when you get around to it.