It's important to remain aware that the serial layer's flush and drain
semantics differs from e.g. filesystem calls. The libserialport API is
said to follow the termios example.
Extend comments in the libsigrok API, to not depend on the libserialport
layer and the availability of its documentation. This raises awareness
during maintenance of sigrok device drivers, as well as the pending
addition of alternative transports for serial communication.
Adjust the doxygen comment for the read line routine while we are here.
Add "in" and "out" attributes for routine parameters.
- * Flush serial port buffers.
+ * Flush serial port buffers. Empty buffers, discard pending RX and TX data.
*
* @param serial Previously initialized serial port structure.
*
*
* @param serial Previously initialized serial port structure.
*
- * Drain serial port buffers.
+ * Drain serial port buffers. Wait for pending TX data to be sent.
*
* @param serial Previously initialized serial port structure.
*
*
* @param serial Previously initialized serial port structure.
*
/**
* Read a line from the specified serial port.
*
/**
* Read a line from the specified serial port.
*
- * @param serial Previously initialized serial port structure.
- * @param buf Buffer where to store the bytes that are read.
- * @param buflen Size of the buffer.
+ * @param[in] serial Previously initialized serial port structure.
+ * @param[out] buf Buffer where to store the bytes that are read.
+ * @param[in] buflen Size of the buffer.
* @param[in] timeout_ms How long to wait for a line to come in.
*
* @param[in] timeout_ms How long to wait for a line to come in.
*
- * Reading stops when CR of LR is found, which is stripped from the buffer.
+ * Reading stops when CR or LF is found, which is stripped from the buffer.
*
* @retval SR_OK Success.
* @retval SR_ERR Failure.
*
* @retval SR_OK Success.
* @retval SR_ERR Failure.