Assign a new method name for the port name setting API

* This is more intuitive as it is not setting the port with all its settings
like baud rate, flow control, stop bits, parity, and so forth, but only the port
name.

* This will allow in upcoming change to establish a property for the port name
along with a port name changed signal to be useful from different threads, QML,
and so forth.

* Clean up the documentation not to provide internal information to the end
users, and also make the text a bit more concise and better readable.

* Examples are also changed accordingly, to use the new API.

Change-Id: Idbaa8ee2dee17c63fc0278f687ccc231c5ab670f
Reviewed-by: Denis Shienkov <denis.shienkov@gmail.com>

9 files changed, 21 insertions, 20 deletions

diff --git a/examples/blockingmaster/masterthread.cpp b/examples/blockingmaster/masterthread.cpp
index 1ca38f48..061ddd6e 100644
--- a/examples/blockingmaster/masterthread.cpp
+++ b/examples/blockingmaster/masterthread.cpp
@@ -102,7 +102,7 @@ void MasterThread::run()
         //![6] //! [7]
         if (currentPortNameChanged) {
             serial.close();
-            serial.setPort(currentPortName);
+            serial.setPortName(currentPortName);
 
             if (!serial.open(QIODevice::ReadWrite)) {
                 emit error(tr("Can't open %1, error code %2")
diff --git a/examples/blockingslave/slavethread.cpp b/examples/blockingslave/slavethread.cpp
index 9b49edba..a31db256 100644
--- a/examples/blockingslave/slavethread.cpp
+++ b/examples/blockingslave/slavethread.cpp
@@ -98,7 +98,7 @@ void SlaveThread::run()
 //![6] //! [7]
         if (currentPortNameChanged) {
             serial.close();
-            serial.setPort(currentPortName);
+            serial.setPortName(currentPortName);
 
             if (!serial.open(QIODevice::ReadWrite)) {
                 emit error(tr("Can't open %1, error code %2")
diff --git a/examples/master/dialog.cpp b/examples/master/dialog.cpp
index 0a27575c..e3a4b66e 100644
--- a/examples/master/dialog.cpp
+++ b/examples/master/dialog.cpp
@@ -100,7 +100,7 @@ void Dialog::sendRequest()
 {
     if (serial.portName() != serialPortComboBox->currentText()) {
         serial.close();
-        serial.setPort(serialPortComboBox->currentText());
+        serial.setPortName(serialPortComboBox->currentText());
 
         if (!serial.open(QIODevice::ReadWrite)) {
             processError(tr("Can't open %1, error code %2")
diff --git a/examples/slave/dialog.cpp b/examples/slave/dialog.cpp
index ddae52a0..06a2a152 100644
--- a/examples/slave/dialog.cpp
+++ b/examples/slave/dialog.cpp
@@ -107,7 +107,7 @@ void Dialog::startSlave()
 {
     if (serial.portName() != serialPortComboBox->currentText()) {
         serial.close();
-        serial.setPort(serialPortComboBox->currentText());
+        serial.setPortName(serialPortComboBox->currentText());
 
         if (!serial.open(QIODevice::ReadWrite)) {
             processError(tr("Can't open %1, error code %2")
diff --git a/examples/slave/slavethread.cpp b/examples/slave/slavethread.cpp
index 2a32454e..a0177ffa 100644
--- a/examples/slave/slavethread.cpp
+++ b/examples/slave/slavethread.cpp
@@ -92,7 +92,7 @@ void SlaveThread::run()
 
         if (currentPortNameChanged) {
             serial.close();
-            serial.setPort(currentPortName);
+            serial.setPortName(currentPortName);
 
             if (!serial.open(QIODevice::ReadWrite)) {
                 emit error(tr("Can't open %1, error code %2")
diff --git a/examples/terminal/mainwindow.cpp b/examples/terminal/mainwindow.cpp
index b0e7b2c7..cde83e14 100644
--- a/examples/terminal/mainwindow.cpp
+++ b/examples/terminal/mainwindow.cpp
@@ -87,7 +87,7 @@ MainWindow::~MainWindow()
 void MainWindow::openSerialPort()
 {
     SettingsDialog::Settings p = settings->settings();
-    serial->setPort(p.name);
+    serial->setPortName(p.name);
     if (serial->open(QIODevice::ReadWrite)) {
         if (serial->setBaudRate(p.baudRate)
                 && serial->setDataBits(p.dataBits)
diff --git a/src/serialport/qserialport.cpp b/src/serialport/qserialport.cpp
index c30d7d56..61042910 100644
--- a/src/serialport/qserialport.cpp
+++ b/src/serialport/qserialport.cpp
@@ -426,14 +426,14 @@ QSerialPort::~QSerialPort()
 }
 
 /*!
-    Sets the \a name of the port. The name may be in any format;
-    either short, or also as system location (with all the prefixes and
-    postfixed). As a result, this name will be automatically written
-    and converted into an internal variable as system location.
+    Sets the \a name of the serial port.
+
+    The name of the serial port can be passed on as either a short name or
+    the long system location if necessary.
 
     \sa portName(), QSerialPortInfo
 */
-void QSerialPort::setPort(const QString &name)
+void QSerialPort::setPortName(const QString &name)
 {
     Q_D(QSerialPort);
     d->systemLocation = QSerialPortPrivate::portNameToSystemLocation(name);
diff --git a/src/serialport/qserialport.h b/src/serialport/qserialport.h
index 213aba9a..aa87eba9 100644
--- a/src/serialport/qserialport.h
+++ b/src/serialport/qserialport.h
@@ -164,10 +164,11 @@ public:
     explicit QSerialPort(const QSerialPortInfo &info, QObject *parent = 0);
     virtual ~QSerialPort();
 
-    void setPort(const QString &port);
-    void setPort(const QSerialPortInfo &info);
+    void setPortName(const QString &name);
     QString portName() const;
 
+    void setPort(const QSerialPortInfo &info);
+
     virtual bool open(OpenMode mode);
     virtual void close();
 
diff --git a/tests/manual/qserialport/tst_qserialport.cpp b/tests/manual/qserialport/tst_qserialport.cpp
index 17d4d67d..777c0711 100644
--- a/tests/manual/qserialport/tst_qserialport.cpp
+++ b/tests/manual/qserialport/tst_qserialport.cpp
@@ -95,7 +95,7 @@ void tst_QSerialPort::open()
         QCOMPARE(object1.isOpen(), false);
 
         // Try open and check access to port by Name
-        object1.setPort(serialPortInfo.portName());
+        object1.setPortName(serialPortInfo.portName());
         QCOMPARE(object1.portName(), serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
         QCOMPARE(object1.isOpen(), true);
@@ -103,7 +103,7 @@ void tst_QSerialPort::open()
         QCOMPARE(object1.isOpen(), false);
 
         // Try open and check access to port by Location
-        object1.setPort(serialPortInfo.systemLocation());
+        object1.setPortName(serialPortInfo.systemLocation());
         QCOMPARE(object1.portName(), serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
         QCOMPARE(object1.isOpen(), true);
@@ -117,7 +117,7 @@ void tst_QSerialPort::baudRate()
     foreach (const QSerialPortInfo &serialPortInfo, serialPortInfoList) {
 
         QSerialPort object1;
-        object1.setPort(serialPortInfo.portName());
+        object1.setPortName(serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
 
         QCOMPARE(object1.setBaudRate(QSerialPort::Baud1200), true);
@@ -146,7 +146,7 @@ void tst_QSerialPort::dataBits()
     foreach (const QSerialPortInfo &serialPortInfo, serialPortInfoList) {
 
         QSerialPort object1;
-        object1.setPort(serialPortInfo.portName());
+        object1.setPortName(serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
 
         QCOMPARE(object1.setDataBits(QSerialPort::Data8), true);
@@ -161,7 +161,7 @@ void tst_QSerialPort::parity()
     foreach (const QSerialPortInfo &serialPortInfo, serialPortInfoList) {
 
         QSerialPort object1;
-        object1.setPort(serialPortInfo.portName());
+        object1.setPortName(serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
 
         QCOMPARE(object1.setParity(QSerialPort::NoParity), true);
@@ -184,7 +184,7 @@ void tst_QSerialPort::stopBits()
     foreach (const QSerialPortInfo &serialPortInfo, serialPortInfoList) {
 
         QSerialPort object1;
-        object1.setPort(serialPortInfo.portName());
+        object1.setPortName(serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
 
         QCOMPARE(object1.setStopBits(QSerialPort::OneStop), true);
@@ -202,7 +202,7 @@ void tst_QSerialPort::flowControl()
     foreach (const QSerialPortInfo &serialPortInfo, serialPortInfoList) {
 
         QSerialPort object1;
-        object1.setPort(serialPortInfo.portName());
+        object1.setPortName(serialPortInfo.portName());
         QCOMPARE(object1.open(QIODevice::ReadWrite), true);
 
         QCOMPARE(object1.setFlowControl(QSerialPort::NoFlowControl), true);