UG: Document that Union[str, int] convers all args to strings.

pekkaklarck · pekkaklarck · commit 398e60b307df · 2021-02-26T19:23:32.000+02:00
Better to use Union[int, str]. Related to robotframework#3738. Fixes robotframework#3867.
diff --git a/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.rst b/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.rst
@@ -1541,7 +1541,8 @@ Specifying multiple possible types
 Starting from Robot Framework 4.0, it is possible to specify that an argument
 has multiple possible types. In this situation argument conversion is attempted
 based on each type in the order they have been specified. If any conversion
-succeeds, the resulting value is used, and otherwise the whole conversion fails.
+succeeds, the resulting value is used without attempting conversion to remaining
+types. If no type conversion succeeds, the whole conversion fails.
 
 When using function annotations, the natural syntax to specify that argument
 has multiple possible types is using Union_:
@@ -1556,7 +1557,7 @@ has multiple possible types is using Union_:
 
 An alternative is giving types a tuple. It is not recommended with annotations
 because that syntax is not supported by other tools, but it works well with
-the `@keyword` decorator:
+the `@keyword` decorator and is Python 2 compatible:
 
 .. sourcecode:: python
 
@@ -1571,6 +1572,12 @@ With the above examples the `length` argument would first be converted to an
 integer and if that fails then to a float. The `padding` would be first
 converted to `None`, then to an integer, and finally to a string.
 
+Because conversion is attempted one-by-one and string conversion always succeeds,
+possible `str` should be the last type. For example, using `Union[str, int]` would
+cause all arguments, including integers, to be converted to strings, but
+`Union[int, str]` means that integer conversion is attempted first and string
+conversion is done only if that fails.
+
 If any of the specified types is not recognized by Robot Framework and
 the given argument cannot be converted to any of the types before it,
 the given argument will be used as-is. For example, with this keyword
