QUrl/doc: explain that the scheme-less URL is probably not intended

It is a valid URL reference, which is not what people may want.

Fixes: QTBUG-109855
Pick-to: 6.4 6.5
Change-Id: I69ecc04064514f939896fffd173783ce2228c1d2
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

src/corelib/doc/snippets/code/src_corelib_io_qurl.cpp

@@ -1,6 +1,14 @@
 // Copyright (C) 2016 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
+//! [constructor-url-reference]
+QUrl url("example.com");
+//! [constructor-url-reference]
+
+//! [constructor-url]
+QUrl url("https://example.com");
+//! [constructor-url]
+
 //! [0]
 QUrl url("http://www.example.com/List of holidays.xml");
 // url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"

src/corelib/io/qurl.cpp

@@ -14,14 +14,16 @@
     \ingroup network
     \ingroup shared
 
-
     It can parse and construct URLs in both encoded and unencoded
     form. QUrl also has support for internationalized domain names
     (IDNs).
 
-    The most common way to use QUrl is to initialize it via the
-    constructor by passing a QString. Otherwise, setUrl() can also
-    be used.
+    The most common way to use QUrl is to initialize it via the constructor by
+    passing a QString containing a full URL. QUrl objects can also be created
+    from a QByteArray containing a full URL using QUrl::fromEncoded(), or
+    heuristically from incomplete URLs using QUrl::fromUserInput(). The URL
+    representation can be obtained from a QUrl using either QUrl::toString() or
+    QUrl::toEncoded().
 
     URLs can be represented in two forms: encoded or unencoded. The
     unencoded representation is suitable for showing to users, but
@@ -1789,7 +1791,20 @@ inline void QUrlPrivate::validate() const
 
 
 /*!
-    Constructs a URL by parsing \a url. QUrl will automatically percent encode
+    Constructs a URL by parsing \a url. Note this constructor expects a proper
+    URL or URL-Reference and will not attempt to guess intent. For example, the
+    following declaration:
+
+    \snippet code/src_corelib_io_qurl.cpp constructor-url-reference
+
+    Will construct a valid URL but it may not be what one expects, as the
+    scheme() part of the input is missing. For a string like the above,
+    applications may want to use fromUserInput(). For this constructor or
+    setUrl(), the following is probably what was intended:
+
+    \snippet code/src_corelib_io_qurl.cpp constructor-url
+
+    QUrl will automatically percent encode
     all characters that are not allowed in a URL and decode the percent-encoded
     sequences that represent an unreserved character (letters, digits, hyphens,
     underscores, dots and tildes). All other characters are left in their