fix JavaScript kw doc

Author: ombre42

src/Selenium2Library/__init__.py

@@ -28,13 +28,13 @@ class Selenium2Library(
  Selenium2Library runs tests in a real browser instance. It should work in
  most modern browsers and can be used with both Python and Jython interpreters.
 
- *Before running tests*
+ = Before running tests =
 
  Prior to running test cases using Selenium2Library, Selenium2Library must be
  imported into your Robot test suite (see `importing` section), and the 
  `Open Browser` keyword must be used to open a browser to the desired location.
 
- *Locating elements*
+ = Locating elements =
 
  All keywords in Selenium2Library that need to find an element on the page
  take an argument, `locator`. By default, when a locator value is provided,
@@ -72,12 +72,13 @@ class Selenium2Library(
  | css | Table Should Contain `|` css=table.my_class `|` text | Matches by @id or @name attribute |
  | xpath | Table Should Contain `|` xpath=//table/[@name="my_table"] `|` text | Matches by @id or @name attribute |
 
- *Timeouts*
+ = Timeouts =
 
  There are several `Wait ...` keywords that take timeout as an
  argument. All of these timeout arguments are optional. The timeout
  used by all of them can be set globally using the
- `Set Selenium Timeout` keyword.
+ `Set Selenium Timeout` keyword. The same timeout also applies to
+ `Execute Async Javascript`.
 
  All timeouts can be given as numbers considered seconds (e.g. 0.5 or 42)
  or in Robot Framework's time syntax (e.g. '1.5 seconds' or '1 min 30 s').

src/Selenium2Library/keywords/_browsermanagement.py

@@ -418,7 +418,7 @@ def set_selenium_timeout(self, seconds):
  There are several `Wait ...` keywords that take timeout as an
  argument. All of these timeout arguments are optional. The timeout
  used by all of them can be set globally using this keyword.
- See `introduction` for more information about timeouts.
+ See `Timeouts` for more information about timeouts.
 
  The previous timeout value is returned by this keyword and can
  be used to set the old value back later. The default timeout

src/Selenium2Library/keywords/_javascript.py

@@ -68,20 +68,23 @@ def confirm_action(self):
  def execute_javascript(self, *code):
  """Executes the given JavaScript code.
 
- `code` may contain multiple lines of code but must contain a 
- return statement (with the value to be returned) at the end.
-
- `code` may be divided into multiple cells in the test data. In that
- case, the parts are catenated together without adding spaces.
+ `code` may contain multiple lines of code and may be divided into
+ multiple cells in the test data. In that case, the parts are
+ catenated together without adding spaces.
 
  If `code` is an absolute path to an existing file, the JavaScript
  to execute will be read from that file. Forward slashes work as
  a path separator on all operating systems.
 
- Note that, by default, the code will be executed in the context of the
- Selenium object itself, so `this` will refer to the Selenium object.
- Use `window` to refer to the window of your application, e.g.
- `window.document.getElementById('foo')`.
+ The JavaScript executes in the context of the currently selected
+ frame or window. Use _window_ to refer to the window of your
+ application and _document_ to refer to the document object
+ of the current frame or window, e.g.
+ _document.getElementById('foo')_.
+
+ This keyword returns None unless there is a return statement in the
+ JavaScript. Return values are converted to the appropriate type in
+ Python, including WebElements.
 
  Example:
  | Execute JavaScript | window.my_js_function('arg1', 'arg2') |
@@ -94,24 +97,17 @@ def execute_javascript(self, *code):
  def execute_async_javascript(self, *code):
  """Executes asynchronous JavaScript code.
 
- `code` may contain multiple lines of code but must contain a 
- return statement (with the value to be returned) at the end.
-
- `code` may be divided into multiple cells in the test data. In that
- case, the parts are catenated together without adding spaces.
-
- If `code` is an absolute path to an existing file, the JavaScript
- to execute will be read from that file. Forward slashes work as
- a path separator on all operating systems.
+ Similar to `Execute Javascript` except that scripts executed with
+ this keyword must explicitly signal they are finished by invoking the
+ provided callback. This callback is always injected into the executed
+ function as the last argument.
 
- Note that, by default, the code will be executed in the context of the
- Selenium object itself, so `this` will refer to the Selenium object.
- Use `window` to refer to the window of your application, e.g.
- `window.document.getElementById('foo')`.
+ Scripts must complete within the script timeout or this keyword will
+ fail. See the `Timeouts` section for more information.
 
  Example:
- | Execute Async JavaScript | window.my_js_function('arg1', 'arg2') |
- | Execute Async JavaScript | ${CURDIR}/js_to_execute.js |
+ | Execute Async JavaScript | var callback = arguments[arguments.length - 1]; | window.setTimeout(callback, 2000); |
+ | Execute Async JavaScript | ${CURDIR}/async_js_to_execute.js | |
  """
  js = self._get_javascript_to_execute(''.join(code))
  self._info("Executing Asynchronous JavaScript:\n%s" % js)