Improve SerialPortManager.getIdentifiers() JavaDoc (openhab#1471)

* Improve SerialPortManager.getIdentifiers() JavaDoc

The current JavaDocs do not clearly state that it does not always return all identifiers.
E.g. it will not return any RFC2217 identifiers or undiscovered RXTX port identifiers.
So it should not be used to search for an identifier when the serial port name is known.
This method is useful for listing available port options in UIs and logging.

Signed-off-by: Wouter Born <github@maindrain.net>

bundles/org.openhab.core.io.transport.serial/src/main/java/org/openhab/core/io/transport/serial/SerialPortManager.java

@@ -41,9 +41,12 @@ public interface SerialPortManager {
     }
 
     /**
-     * Gets the serial port identifiers.
+     * Gets the discovered serial port identifiers.
      *
-     * @return stream of serial port identifiers
+     * {@link SerialPortProvider}s may not be able to discover any or all identifiers.
+     * When the port name is known, the preferred way to get an identifier is by using {@link #getIdentifier(String)}.
+     *
+     * @return stream of discovered serial port identifiers
      */
     Stream<SerialPortIdentifier> getIdentifiers();
 }