BLAHAJ
/
libsigrok
10
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

serial: update doxygen comments (flush vs drain, in vs out params) 

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.
This commit is contained in:
Gerhard Sittig 2017-03-19 16:11:56 +01:00
parent fcfa36fd6f
commit 6213c38ef8
1 changed files with 6 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/serial.c
View File

@ -153,7 +153,7 @@ SR_PRIV int serial_close(struct sr_serial_dev_inst *serial)
}
/**
* Flush serial port buffers.
* Flush serial port buffers. Empty buffers, discard pending RX and TX data.
*
* @param serial Previously initialized serial port structure.
*
@ -197,7 +197,7 @@ SR_PRIV int serial_flush(struct sr_serial_dev_inst *serial)
}
/**
* Drain serial port buffers.
* Drain serial port buffers. Wait for pending TX data to be sent.
*
* @param serial Previously initialized serial port structure.
*
@ -595,12 +595,12 @@ SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial,
/**
* 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.
*
* 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.