doc update
diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst
index a3f2ae8..9063ef2 100644
--- a/documentation/pyserial_api.rst
+++ b/documentation/pyserial_api.rst
@@ -80,14 +80,20 @@
OSX >= Tiger, Windows). Though, even on these platforms some serial
ports may reject non-standard values.
- Possible values for the parameter *timeout*:
+ Possible values for the parameter *timeout* which controls the behavior
+ of :meth:`read`:
- - ``timeout = None``: wait forever
- - ``timeout = 0``: non-blocking mode (return immediately on read)
+ - ``timeout = None``: wait forever / until requested number of bytes
+ are received
+ - ``timeout = 0``: non-blocking mode, return immediately in any case,
+ returning zero or more, up to the requested number of bytes
- ``timeout = x``: set timeout to ``x`` seconds (float allowed)
+ returns immediately when the requested number of bytes are available,
+ otherwise wait until the timeout expires and return all bytes that
+ were received until then.
- Writes are blocking by default, unless *write_timeout* is set. For
- possible values refer to the list for *timeout* above.
+ :meth:`write` is blocking by default, unless *write_timeout* is set.
+ For possible values refer to the list for *timeout* above.
Note that enabling both flow control methods (*xonxoff* and *rtscts*)
together may not be supported. It is common to use one of the methods
@@ -101,6 +107,7 @@
.. versionchanged:: 2.5
*dsrdtr* now defaults to ``False`` (instead of *None*)
+ .. versionchanged:: 3.0 numbers as *port* argument are no longer supported
.. method:: open()
@@ -122,6 +129,7 @@
:param size: Number of bytes to read.
:return: Bytes read from the port.
+ :rtype: bytes
Read *size* bytes from the serial port. If a timeout is set it may
return less characters as requested. With no timeout it will block
@@ -135,6 +143,7 @@
:param data: Data to send.
:return: Number of bytes written.
+ :rtype: int
:exception SerialTimeoutException:
In case a write timeout is configured for the port and the time is
exceeded.
@@ -143,7 +152,7 @@
(or compatible such as ``bytearray`` or ``memoryview``). Unicode
strings must be encoded (e.g. ``'hello'.encode('utf-8'``).
- .. versionchanged:: 2.5
+ .. versionchanged:: 2.5
Accepts instances of :class:`bytes` and :class:`bytearray` when
available (Python 2.6 and newer) and :class:`str` otherwise.
@@ -365,7 +374,7 @@
:setter: Disable (``None``) or enable the RS485 settings
:type: :class:`rs485.RS485Settings` or ``None``
:platform: Posix (Linux, limited set of hardware)
- :platform: Windows (RTS on TX only possible)
+ :platform: Windows (only RTS on TX possible)
Attribute to configure RS485 support. When set to an instance of
:class:`rs485.RS485Settings` and supported by OS, RTS will be active
@@ -380,9 +389,9 @@
.. attribute:: BAUDRATES
- A list of valid baud rates. The list may be incomplete such that higher
- baud rates may be supported by the device and that values in between the
- standard baud rates are supported. (Read Only).
+ A list of valid baud rates. The list may be incomplete, such that higher
+ and/or intermediate baud rates may also be supported by the device
+ (Read Only).
.. attribute:: BYTESIZES
@@ -432,6 +441,7 @@
.. method:: get_settings()
:return: a dictionary with current port settings.
+ :rtype: dict
Get a dictionary with port settings. This is useful to backup the
current settings so that a later point in time they can be restored
@@ -440,18 +450,20 @@
Note that control lines (RTS/DTR) are part of the settings.
.. versionadded:: 2.5
+ .. versionchanged:: 3.0 renamed from ``getSettingsDict``
.. method:: apply_settings(d)
- :param d: a dictionary with port settings.
+ :param dict d: a dictionary with port settings.
Applies a dictionary that was created by :meth:`get_settings`. Only
- changes are applied and when a key is missing it means that the setting
- stays unchanged.
+ changes are applied and when a key is missing, it means that the
+ setting stays unchanged.
Note that control lines (RTS/DTR) are not changed.
.. versionadded:: 2.5
+ .. versionchanged:: 3.0 renamed from ``applySettingsDict``
Platform specific methods.
@@ -477,7 +489,7 @@
.. method:: set_input_flow_control(enable)
:platform: Posix
- :param enable: Set flow control state.
+ :param bool enable: Set flow control state.
Manually control flow - when software flow control is enabled.
@@ -490,7 +502,7 @@
:platform: Posix (HW and SW flow control)
:platform: Windows (SW flow control only)
- :param enable: Set flow control state.
+ :param bool enable: Set flow control state.
Manually control flow of outgoing data - when hardware or software flow
control is enabled.