Doc: Move literal code block to a separate file

We need to override this snippet for the documentation
we generate for Qt for Python, and it is easier to have
it on a separate file.

Task-number: PYSIDE-801
Task-number: PYSIDE-691
Change-Id: Ideb5b6af25024279f167137d3b65660bb9c96a7e
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

6 files changed, 28 insertions, 185 deletions

diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp
index 2e825d2373..4d56d1a179 100644
--- a/src/corelib/io/qdebug.cpp
+++ b/src/corelib/io/qdebug.cpp
@@ -606,31 +606,7 @@ QDebug &QDebug::resetFormat()
     clean.
 
     Output examples:
-    \code
-        QString s;
-
-        s = "a";
-        qDebug().noquote() << s;    // prints: a
-        qDebug() << s;              // prints: "a"
-
-        s = "\"a\r\n\"";
-        qDebug() << s;              // prints: "\"a\r\n\""
-
-        s = "\033";                 // escape character
-        qDebug() << s;              // prints: "\u001B"
-
-        s = "\u00AD";               // SOFT HYPHEN
-        qDebug() << s;              // prints: "\u00AD"
-
-        s = "\u00E1";               // LATIN SMALL LETTER A WITH ACUTE
-        qDebug() << s;              // prints: "á"
-
-        s = "a\u0301";              // "a" followed by COMBINING ACUTE ACCENT
-        qDebug() << s;              // prints: "á";
-
-        s = "\u0430\u0301";         // CYRILLIC SMALL LETTER A followed by COMBINING ACUTE ACCENT
-        qDebug() << s;              // prints: "а́"
-    \endcode
+    \snippet code/src_corelib_io_qdebug.cpp 0
 */
 
 /*!
@@ -690,25 +666,7 @@ QDebug &QDebug::resetFormat()
     clean.
 
     Output examples:
-    \code
-        QByteArray ba;
-
-        ba = "a";
-        qDebug().noquote() << ba;    // prints: a
-        qDebug() << ba;              // prints: "a"
-
-        ba = "\"a\r\n\"";
-        qDebug() << ba;              // prints: "\"a\r\n\""
-
-        ba = "\033";                 // escape character
-        qDebug() << ba;              // prints: "\x1B"
-
-        ba = "\xC3\xA1";
-        qDebug() << ba;              // prints: "\xC3\xA1"
-
-        ba = QByteArray("a\0b", 3);
-        qDebug() << ba               // prints: "\a\x00""b"
-    \endcode
+    \snippet code/src_corelib_io_qdebug.cpp 1
 
     Note how QDebug needed to close and reopen the string in the way C and C++
     languages concatenate string literals so that the letter 'b' is not
diff --git a/src/corelib/io/qfileselector.cpp b/src/corelib/io/qfileselector.cpp
index 0ba8b124f7..ce06c8e00b 100644
--- a/src/corelib/io/qfileselector.cpp
+++ b/src/corelib/io/qfileselector.cpp
@@ -81,27 +81,11 @@ QFileSelectorPrivate::QFileSelectorPrivate()
     Consider the following example usage, where you want to use different settings files on
     different locales. You might select code between locales like this:
 
-    \code
-    QString defaultsBasePath = "data/";
-    QString defaultsPath = defaultsBasePath + "defaults.conf";
-    QString localizedPath = defaultsBasePath
-            + QString("%1/defaults.conf").arg(QLocale().name());
-    if (QFile::exists(localizedPath))
-        defaultsPath = localizedPath;
-    QFile defaults(defaultsPath);
-    \endcode
+    \snippet code/src_corelib_io_qfileselector.cpp 0
 
     Similarly, if you want to pick a different data file based on target platform,
     your code might look something like this:
-    \code
-    QString defaultsPath = "data/defaults.conf";
-#if defined(Q_OS_ANDROID)
-    defaultsPath = "data/android/defaults.conf";
-#elif defined(Q_OS_IOS)
-    defaultsPath = "data/ios/defaults.conf";
-#endif
-    QFile defaults(defaultsPath);
-    \endcode
+    \snippet code/src_corelib_io_qfileselector.cpp 1
 
     QFileSelector provides a convenient alternative to writing such boilerplate code, and in the
     latter case it allows you to start using an platform-specific configuration without a recompile.
@@ -109,27 +93,17 @@ QFileSelectorPrivate::QFileSelectorPrivate()
     selecting a different file only on certain combinations of platform and locale. For example, to
     select based on platform and/or locale, the code is as follows:
 
-    \code
-    QFileSelector selector;
-    QFile defaultsFile(selector.select("data/defaults.conf"));
-    \endcode
+    \snippet code/src_corelib_io_qfileselector.cpp 2
 
     The files to be selected are placed in directories named with a \c'+' and a selector name. In the above
     example you could have the platform configurations selected by placing them in the following locations:
-    \code
-    data/defaults.conf
-    data/+android/defaults.conf
-    data/+ios/+en_GB/defaults.conf
-    \endcode
+    \snippet code/src_corelib_io_qfileselector.cpp 3
 
     To find selected files, QFileSelector looks in the same directory as the base file. If there are
     any directories of the form +<selector> with an active selector, QFileSelector will prefer a file
     with the same file name from that directory over the base file. These directories can be nested to
     check against multiple selectors, for example:
-    \code
-    images/background.png
-    images/+android/+en_GB/background.png
-    \endcode
+    \snippet code/src_corelib_io_qfileselector.cpp 4
     With those files available, you would select a different file on the android platform,
     but only if the locale was en_GB.
 
@@ -178,13 +152,7 @@ QFileSelectorPrivate::QFileSelectorPrivate()
     credentials. The example is sorted so that the lowest matching file would be chosen if all
     selectors were present:
 
-    \code
-    images/background.png
-    images/+linux/background.png
-    images/+windows/background.png
-    images/+admin/background.png
-    images/+admin/+linux/background.png
-    \endcode
+    \snippet code/src_corelib_io_qfileselector.cpp 5
 
     Because extra selectors are checked before platform the \c{+admin/background.png} will be chosen
     on Windows when the admin selector is set, and \c{+windows/background.png} will be chosen on
diff --git a/src/corelib/io/qloggingcategory.cpp b/src/corelib/io/qloggingcategory.cpp
index aa84f56368..33253429a2 100644
--- a/src/corelib/io/qloggingcategory.cpp
+++ b/src/corelib/io/qloggingcategory.cpp
@@ -135,9 +135,7 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
     flexible way. Rules are specified in text, where every line must have the
     format
 
-    \code
-    <category>[.<type>] = true|false
-    \endcode
+    \snippet code/src_corelib_io_qloggingcategory.cpp 0
 
     \c <category> is the name of the category, potentially with \c{*} as a
     wildcard symbol as the first or last character (or at both positions).
@@ -149,10 +147,7 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
 
     Rules can be set via \l setFilterRules():
 
-    \code
-    QLoggingCategory::setFilterRules("*.debug=false\n"
-                                     "driver.usb.debug=true");
-    \endcode
+    \snippet code/src_corelib_io_qloggingcategory.cpp 1
 
     Since Qt 5.3, logging rules are also
     automatically loaded from the \c [Rules] section of a logging
@@ -160,19 +155,13 @@ static void setBoolLane(QBasicAtomicInt *atomic, bool enable, int shift)
     configuration directory, or explicitly set in a \c QT_LOGGING_CONF
     environment variable:
 
-    \code
-    [Rules]
-    *.debug=false
-    driver.usb.debug=true
-    \endcode
+    \snippet code/src_corelib_io_qloggingcategory.cpp 2
 
     Since Qt 5.3, logging rules can also be specified in a \c QT_LOGGING_RULES
     environment variable. And since Qt 5.6, multiple rules can also be
     separated by semicolons:
 
-    \code
-    QT_LOGGING_RULES="*.debug=false;driver.usb.debug=true"
-    \endcode
+    \snippet code/src_corelib_io_qloggingcategory.cpp 3
 
     Rules set by \l setFilterRules() take precedence over rules specified
     in the QtProject configuration directory, and can, in turn, be
diff --git a/src/corelib/io/qtemporaryfile.cpp b/src/corelib/io/qtemporaryfile.cpp
index 1983a22c65..7e3be9ef36 100644
--- a/src/corelib/io/qtemporaryfile.cpp
+++ b/src/corelib/io/qtemporaryfile.cpp
@@ -893,13 +893,7 @@ bool QTemporaryFile::rename(const QString &newName)
 
   For example:
 
-  \code
-  QFile f(":/resources/file.txt");
-  QTemporaryFile::createNativeFile(f); // Returns a pointer to a temporary file
-
-  QFile f("/users/qt/file.txt");
-  QTemporaryFile::createNativeFile(f); // Returns 0
-  \endcode
+  \snippet code/src_corelib_io_qtemporaryfile.cpp 1
 
   \sa QFileInfo::isNativePath()
 */
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index 15785b48e0..b324df53b2 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -116,27 +116,12 @@
     Calling isRelative() will return whether or not the URL is relative.
     A relative URL has no \l {scheme}. For example:
 
-    \code
-    qDebug() << QUrl("main.qml").isRelative();          // true: no scheme
-    qDebug() << QUrl("qml/main.qml").isRelative();      // true: no scheme
-    qDebug() << QUrl("file:main.qml").isRelative();     // false: has "file" scheme
-    qDebug() << QUrl("file:qml/main.qml").isRelative(); // false: has "file" scheme
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 8
 
     Notice that a URL can be absolute while containing a relative path, and
     vice versa:
 
-    \code
-    // Absolute URL, relative path
-    QUrl url("file:file.txt");
-    qDebug() << url.isRelative();                 // false: has "file" scheme
-    qDebug() << QDir::isAbsolutePath(url.path()); // false: relative path
-
-    // Relative URL, absolute path
-    url = QUrl("/home/user/file.txt");
-    qDebug() << url.isRelative();                 // true: has no scheme
-    qDebug() << QDir::isAbsolutePath(url.path()); // true: absolute path
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 9
 
     A relative URL can be resolved by passing it as an argument to resolved(),
     which returns an absolute URL. isParentOf() is used for determining whether
@@ -369,14 +354,7 @@
 
     The following example illustrates the problem:
 
-    \code
-        QUrl original("http://example.com/?q=a%2B%3Db%26c");
-        QUrl copy(original);
-        copy.setQuery(copy.query(QUrl::FullyDecoded), QUrl::DecodedMode);
-
-        qDebug() << original.toString();   // prints: http://example.com/?q=a%2B%3Db%26c
-        qDebug() << copy.toString();       // prints: http://example.com/?q=a+=b&c
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 10
 
     If the two URLs were used via HTTP GET, the interpretation by the web
     server would probably be different. In the first case, it would interpret
@@ -1991,10 +1969,7 @@ void QUrl::setUrl(const QString &url, ParsingMode parsingMode)
     \image qurl-authority2.png
 
     To set the scheme, the following call is used:
-    \code
-        QUrl url;
-        url.setScheme("ftp");
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 11
 
     The scheme can also be empty, in which case the URL is interpreted
     as relative.
@@ -2569,11 +2544,7 @@ void QUrl::setPath(const QString &path, ParsingMode mode)
 /*!
     Returns the path of the URL.
 
-    \code
-    qDebug() << QUrl("file:file.txt").path();                   // "file.txt"
-    qDebug() << QUrl("/home/user/file.txt").path();             // "/home/user/file.txt"
-    qDebug() << QUrl("http://www.example.com/test/123").path(); // "/test/123"
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 12
 
     The \a options argument controls how to format the path component. All
     values produce an unambiguous result. With QUrl::FullyDecoded, all
@@ -2588,27 +2559,18 @@ void QUrl::setPath(const QString &path, ParsingMode mode)
     An example of data loss is when you have non-Unicode percent-encoded sequences
     and use FullyDecoded (the default):
 
-    \code
-    qDebug() << QUrl("/foo%FFbar").path();
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 13
 
     In this example, there will be some level of data loss because the \c %FF cannot
     be converted.
 
     Data loss can also occur when the path contains sub-delimiters (such as \c +):
 
-    \code
-    qDebug() << QUrl("/foo+bar%2B").path(); // "/foo+bar+"
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 14
 
     Other decoding examples:
 
-    \code
-    const QUrl url("/tmp/Mambo %235%3F.mp3");
-    qDebug() << url.path(QUrl::FullyDecoded);  // "/tmp/Mambo #5?.mp3"
-    qDebug() << url.path(QUrl::PrettyDecoded); // "/tmp/Mambo #5?.mp3"
-    qDebug() << url.path(QUrl::FullyEncoded);  // "/tmp/Mambo%20%235%3F.mp3"
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 15
 
     \sa setPath()
 */
@@ -3859,40 +3821,22 @@ bool QUrl::isDetached() const
 
     An empty \a localFile leads to an empty URL (since Qt 5.4).
 
-    \code
-    qDebug() << QUrl::fromLocalFile("file.txt");            // QUrl("file:file.txt")
-    qDebug() << QUrl::fromLocalFile("/home/user/file.txt"); // QUrl("file:///home/user/file.txt")
-    qDebug() << QUrl::fromLocalFile("file:file.txt");       // doesn't make sense; expects path, not url with scheme
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 16
 
     In the first line in snippet above, a file URL is constructed from a
     local, relative path. A file URL with a relative path only makes sense
     if there is a base URL to resolve it against. For example:
 
-    \code
-    QUrl url = QUrl::fromLocalFile("file.txt");
-    QUrl baseUrl = QUrl("file:/home/user/");
-    // wrong: prints QUrl("file:file.txt"), as url already has a scheme
-    qDebug() << baseUrl.resolved(url);
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 17
 
     To resolve such a URL, it's necessary to remove the scheme beforehand:
 
-    \code
-    // correct: prints QUrl("file:///home/user/file.txt")
-    url.setScheme(QString());
-    qDebug() << baseUrl.resolved(url);
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 18
 
     For this reason, it is better to use a relative URL (that is, no scheme)
     for relative file paths:
 
-    \code
-    QUrl url = QUrl("file.txt");
-    QUrl baseUrl = QUrl("file:/home/user/");
-    // prints QUrl("file:///home/user/file.txt")
-    qDebug() << baseUrl.resolved(url);
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 19
 
     \sa toLocalFile(), isLocalFile(), QDir::toNativeSeparators()
 */
@@ -3938,11 +3882,7 @@ QUrl QUrl::fromLocalFile(const QString &localFile)
     returned value in the form found on SMB networks (for example,
     "//servername/path/to/file.txt").
 
-    \code
-    qDebug() << QUrl("file:file.txt").toLocalFile();            // "file:file.txt"
-    qDebug() << QUrl("file:/home/user/file.txt").toLocalFile(); // "file:///home/user/file.txt"
-    qDebug() << QUrl("file.txt").toLocalFile();                 // ""; wasn't a local file as it had no scheme
-    \endcode
+    \snippet code/src_corelib_io_qurl.cpp 20
 
     Note: if the path component of this URL contains a non-UTF-8 binary
     sequence (such as %80), the behaviour of this function is undefined.
diff --git a/src/corelib/io/qurlquery.cpp b/src/corelib/io/qurlquery.cpp
index 231a26c211..97e7b8a4eb 100644
--- a/src/corelib/io/qurlquery.cpp
+++ b/src/corelib/io/qurlquery.cpp
@@ -129,10 +129,7 @@ QT_BEGIN_NAMESPACE
   Non-standard delimiters should be chosen from among what RFC 3986 calls
   "sub-delimiters". They are:
 
-  \code
-    sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
-                  / "*" / "+" / "," / ";" / "="
-  \endcode
+  \snippet code/src_corelib_io_qurlquery.cpp 0
 
   Use of other characters is not supported and may result in unexpected
   behaviour. QUrlQuery does not verify that you passed a valid delimiter.
@@ -570,10 +567,7 @@ QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding) const
     \note Non-standard delimiters should be chosen from among what RFC 3986 calls
     "sub-delimiters". They are:
 
-    \code
-      sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
-                    / "*" / "+" / "," / ";" / "="
-    \endcode
+    \snippet code/src_corelib_io_qurlquery.cpp 0
 
     Use of other characters is not supported and may result in unexpected
     behaviour. This method does not verify that you passed a valid delimiter.