For properties and method parameters that accept multiple types, documentation should promote the recommended type #1388
Description
Description of issue
The main idea being documentation should guide the users to use the most-pythonic type for any property or method parameter. e.g.:
documentation says:
offsets (list of float in seconds or datetime.timedelta):
In this case, documentation should mention that datetime.timedelta is the recommended type, as that the pythonic way of representing time intervals.
Another instance would be the documentation for repeated capabilities:
Repeated capabilities attributes use the indexing operator [] to indicate the repeated capabilities. The parameter can be a string, list, tuple, or slice (range). Each element of those can be a string or an integer. If it is a string, you can indicate a range using the same format as the driver: ‘0-2’ or ‘0:2’
I think it's still valuable to document all the different types that can be passed in, for cases where the recommended type cannot be used; but there should be a clear distinction between recommended type and the others.