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

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.