QSerialPort (Windows): Unclear documentation leads to improper use of read() methods

The current QSerialPort documentation at https://doc.qt.io/qt-5/qserialport.html states:

"Once you know that the ports are ready to read or write, you can use the read() or write() methods."

This is stated before any mention of waitForReadyRead or ReadyRead, and furthermore, the documentation does not explicitly mention the fact that either waitForReadyRead OR an event loop MUST be used before read() can be used.  Instead, waitForReadyRead is presented as an optional/non-essential feature for a blocking serial port, and much later on, there is a brief mention that a blocking serial port does not require an event loop (unclearly insinuating that a non-blocking serial port must use an event loop).

The way the documentation is currently written, the user has no idea what the concept of "ready to read" actually means, and may easily confuse that as simply meaning "once the port is opened".

It should be clearly stated up front in the documentation:

• That a QSerialPort can only be used in two ways:
  • Blocking (using waitForReadyRead)
  • Non-Blocking (using an event loop)
• The definition of "ready to read" means that data has been transferred from the port into the QIODevice's read buffer and is available to the user
• A "ready to read" state can can only be achieved through waitForReadyRead or after processEvents is called in an event loop

As a user, I was only able to figure out the above points after delving into the source code of qserialport_win.cpp myself.  Users should not have to deconstruct the source code to learn the basics of how to use the feature properly.

I believe this is a significant documentation issue, as I am certainly not the first person to post on the bugtracker thinking there's something wrong with QSerialPort when instead there's something wrong with the documentation (here's a few for example):

QTBUG-82606

QTBUG-82409

QTBUG-80949

P.S. I've verified the requirement of either waitForReadyRead or an event loop by examining the source code of qserialport_win.cpp since commit a0faf986fccdce1d36f3308dc520cdac001f5264.  The use of alertable IO functions (ReadFileEx in this case) prevents transferring bytes from the port to the qiodevice buffer unless the thread enters an alertable state.  waitForReadyRead does this in a while loop using SleepEx(), and an event loop using processEvents does this with a call to MsgWaitForMultipleObjectsEx().  Thus, bytesAvailable() and read() on the QIODevice will always be 0/empty until waitForReadyRead() is called or processEvents() is called.