UG: Document named args and arg conversion with listeners and modifiers

robotframework#3809

doc/api/code_examples/SelectEveryXthTest.py

@@ -8,9 +8,9 @@
 
 class SelectEveryXthTest(SuiteVisitor):
 
-    def __init__(self, x, start=0):
-        self.x = int(x)
-        self.start = int(start)
+    def __init__(self, x: int, start: int = 0):
+        self.x = x
+        self.start = start
 
     def start_suite(self, suite):
         """Modify suite's tests to contain only every Xth."""

doc/userguide/src/ExecutingTestCases/ConfiguringExecution.rst

@@ -478,7 +478,10 @@ works exactly like when `importing a test library`__.
 If a modifier requires arguments, like the examples below do, they can be
 specified after the modifier name or path using either a colon (`:`) or a
 semicolon (`;`) as a separator. If both are used in the value, the one used
-first is considered to be the actual separator.
+first is considered to be the actual separator. Starting from Robot Framework
+4.0, arguments also support the `named argument syntax`_ as well as `argument
+conversion`__ based on `type hints`__ and `default values`__ the same way
+as keywords do.
 
 If more than one pre-run modifier is needed, they can be specified by using
 the :option:`--prerunmodifier` option multiple times. If similar modifying
@@ -491,10 +494,17 @@ executed test suite and test cases. Most importantly, options related to
 use options like :option:`--include` also with possible dynamically added
 tests.
 
+.. tip:: Modifiers are taken into use from the command line exactly the same
+         way as listeners_. See the `Taking listeners into use`_ section for
+         more information and examples.
+
 .. note:: Prior to Robot Framework 3.2 pre-run modifiers were executed
           after other configuration.
 
 __ `Specifying library to import`_
+__ `Supported conversions`_
+__ `Specifying argument types using function annotations`_
+__ `Implicit argument types based on default values`_
 
 Example: Select every Xth test
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -517,6 +527,9 @@ the file is in the `module search path`_, it could be used like this::
     # Specify the modifier as a name. Run every third test, starting from the second.
     robot --prerunmodifier SelectEveryXthTest:3:1 tests.robot
 
+.. note:: Argument conversion based on type hints like `x: int` in the above
+          example is new in Robot Framework 4.0 and requires Python 3.
+
 Example: Exclude tests by name
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/userguide/src/ExecutingTestCases/OutputFiles.rst

@@ -637,8 +637,8 @@ marks all passed tests that have taken more time than allowed as failed:
 
     class ExecutionTimeChecker(SuiteVisitor):
 
-        def __init__(self, max_seconds):
-            self.max_milliseconds = float(max_seconds) * 1000
+        def __init__(self, max_seconds: float):
+            self.max_milliseconds = max_seconds * 1000
 
         def visit_test(self, test):
             if test.status == 'PASS' and test.elapsedtime > self.max_milliseconds:
@@ -660,6 +660,9 @@ the :option:`--prerebotmodifier` option multiple times. When executing tests,
 it is possible to use :option:`--prerunmodifier` and
 :option:`--prerebotmodifier` options together.
 
+.. note:: Argument conversion based on type hints like `max_seconds: float` in
+          the above example is new in Robot Framework 4.0 and requires Python 3.
+
 System log
 ----------
 

doc/userguide/src/ExtendingRobotFramework/ListenerInterface.rst

@@ -48,9 +48,41 @@ quotes on UNIX-like operating systems::
 
    robot --listener listener.py:arg1:arg2 tests.robot
    robot --listener "listener.py;arg:with:colons" tests.robot
-   robot --listener C:\Path\Listener.py;D:\data;E:\extra tests.robot
+   robot --listener c:\path\listener.py;d:\first\arg;e:\second\arg tests.robot
+
+In addition to passing arguments one-by-one as positional arguments, it is
+possible to pass them using the `named argument syntax`_ exactly when using
+keywords::
+
+   robot --listener listener.py:name=value tests.robot
+   robot --listener "listener.py;name=value:with:colons;another=value" tests.robot
+
+Listener arguments are automatically converted using `same rules as with
+keywords`__ based on `type hints`__ and `default values`__. For example,
+this listener
+
+.. sourcecode:: python
+
+    class Listener(object):
+
+        def __init__(self, port: int, log=True):
+            self.port = post
+            self.log = log
+
+could be used like ::
+
+    robot --listener Listener:8270:false
+
+and the first argument would be converted to an integer based on the type hint
+and the second to a Boolean based on the default value.
+
+.. note:: Both named argument syntax and argument conversion are new in
+          Robot Framework 4.0.
 
 __ `Using physical path to library`_
+__ `Supported conversions`_
+__ `Specifying argument types using function annotations`_
+__ `Implicit argument types based on default values`_
 
 Listener interface versions
 ---------------------------