Doc: Move the common documentation to a qdocinc

The member functions of QStandardPath and
Qt.labs.platform.StandardPath behave the same, so
it's ideal to maintain their documentation in one place.

Task-number: QTBUG-79827
Change-Id: I349dbb85cd9b6a3bedac329c0707fc07057cd64b
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

doc/global/includes/standardpath/functiondocs.qdocinc

@@ -0,0 +1,129 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [displayName]
+
+    Returns a localized display name for the given location \a type
+    or an empty QString if no relevant location can be found.
+
+//! [displayName]
+
+
+//! [findExecutable]
+
+    Finds the executable named \a executableName in the specified
+    \a paths, or the system paths if paths is empty.
+
+    On most operating systems the system path is determined by the
+    \c PATH environment variable. The directories where to search for
+    the executable can be set in the paths argument. To search in
+    both your own paths and the system paths, call findExecutable
+    twice, once with paths set and once with paths empty.
+    Symlinks are not resolved in order to preserve behavior for the
+    case of executables whose behavior depends on the name they are
+    invoked with
+    .
+    \note On Windows, the usual executable extensions (from the PATHEXT
+    environment variable) are automatically appended. For example, the
+    findExecutable("foo") call finds \c foo.exe or \c foo.bat if
+    present.
+
+    Returns the absolute file path to the executable, or an empty
+    string if not found.
+
+//! [findExecutable]
+
+//! [locate]
+
+    Finds a file or directory called \a fileName in the standard
+    locations for \a type.
+
+    The \a options flag lets you specify whether to look for files
+    or directories. By default, this flag is set to \c LocateFile.
+
+    Returns the absolute path to the first file or directory found,
+    otherwise returns an empty string.
+
+//! [locate]
+
+//! [locateAll]
+
+    Finds all files or directories by the name, \a fileName, in the
+    standard locations for \a type.
+
+    The \a options flag lets you specify whether to look for files
+    or directories. By default, this flag is set to \c LocateFile.
+
+    Returns the list of all the files that were found.
+
+//! [locateAll]
+
+//! [setTestModeEnabled]
+
+    If \a testMode is \c true, this enables a special "test mode" in
+    QStandardPaths, which changes writable locations to point to
+    test directories. This prevents auto tests from reading
+    or writing to the current user's configuration.
+
+    It affects the locations into which test programs might write
+    files: \c GenericDataLocation, \c DataLocation, \c ConfigLocation,
+    \c GenericConfigLocation, \c AppConfigLocation,
+    \c GenericCacheLocation, and \c CacheLocation. Other locations
+    are not affected.
+
+    On Unix, \c XDG_DATA_HOME is set to \c{~/.qttest/share},
+    \c XDG_CONFIG_HOME is set to \c{~/.qttest/config}, and
+    \c XDG_CACHE_HOME is set to \c{~/.qttest/cache}.
+
+    On macOS, data goes to \c{~/.qttest/Application Support},
+    cache goes to \c{~/.qttest/Cache}, and config goes to
+    \c{~/.qttest/Preferences}.
+
+    On Windows, everything goes to a "qttest" directory under
+    \c{%APPDATA%}.
+
+//! [setTestModeEnabled]
+
+//! [standardLocations]
+
+    Returns all the directories where files of \a type belong.
+
+    The list of directories is sorted from high to low priority,
+    starting with writableLocation() if it can be determined.
+    This list is empty if no locations for type are defined.
+
+//! [standardLocations]
+
+//! [writableLocation]
+
+    Returns the directory where files of \a type should be written to,
+    or an empty string if the location cannot be determined.
+
+    \note The storage location returned may not exist; that is,
+    it may need to be created by the system or the user.
+
+//! [writableLocation]

src/corelib/io/qstandardpaths.cpp

@@ -357,22 +357,14 @@ QT_BEGIN_NAMESPACE
 /*!
     \fn QString QStandardPaths::writableLocation(StandardLocation type)
 
-    Returns the directory where files of \a type should be written to, or an empty string
+    \include standardpath/functiondoc.qdocinc writableLocation
-    if the location cannot be determined.
-
-    \note The storage location returned can be a directory that does not exist; i.e., it
-    may need to be created by the system or the user.
 */
 
 
 /*!
    \fn QStringList QStandardPaths::standardLocations(StandardLocation type)
 
-   Returns all the directories where files of \a type belong.
+   \include standardpath/functiondoc.qdocinc standardLocations
-
-   The list of directories is sorted from high to low priority, starting with
-   writableLocation() if it can be determined. This list is empty if no locations
-   for \a type are defined.
 
    \sa writableLocation()
  */
@@ -396,11 +388,7 @@ static bool existsAsSpecified(const QString &path, QStandardPaths::LocateOptions
 }
 
 /*!
-   Tries to find a file or directory called \a fileName in the standard locations
+    \include standardpath/functiondoc.qdocinc locate
-   for \a type.
-
-   The full path to the first file or directory (depending on \a options) found is returned.
-   If no such file or directory can be found, an empty string is returned.
  */
 QString QStandardPaths::locate(StandardLocation type, const QString &fileName, LocateOptions options)
 {
@@ -414,12 +402,7 @@ QString QStandardPaths::locate(StandardLocation type, const QString &fileName, L
 }
 
 /*!
-   Tries to find all files or directories called \a fileName in the standard locations
+    \include standardpath/functiondoc.qdocinc locateAll
-   for \a type.
-
-   The \a options flag allows to specify whether to look for files or directories.
-
-   Returns the list of all the files that were found.
  */
 QStringList QStandardPaths::locateAll(StandardLocation type, const QString &fileName, LocateOptions options)
 {
@@ -492,23 +475,7 @@ static inline QString
 #endif // Q_OS_WIN
 
 /*!
-  Finds the executable named \a executableName in the paths specified by \a paths,
+    \include standardpath/functiondoc.qdocinc findExecutable
-  or the system paths if \a paths is empty.
-
-  On most operating systems the system path is determined by the PATH environment variable.
-
-  The directories where to search for the executable can be set in the \a paths argument.
-  To search in both your own paths and the system paths, call findExecutable twice, once with
-  \a paths set and once with \a paths empty.
-
-  Symlinks are not resolved, in order to preserve behavior for the case of executables
-  whose behavior depends on the name they are invoked with.
-
-  \note On Windows, the usual executable extensions (from the PATHEXT environment variable)
-  are automatically appended, so that for instance findExecutable("foo") will find foo.exe
-  or foo.bat if present.
-
-  Returns the absolute file path to the executable, or an empty string if not found.
  */
 QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths)
 {
@@ -566,10 +533,7 @@ QString QStandardPaths::findExecutable(const QString &executableName, const QStr
 }
 
 /*!
-    \fn QString QStandardPaths::displayName(StandardLocation type)
+    \include standardpath/functiondoc.qdocinc displayName
-
-    Returns a localized display name for the given location \a type or
-    an empty QString if no relevant location can be found.
 */
 
 #if !defined(Q_OS_MAC) && !defined(QT_BOOTSTRAPPED)
@@ -626,23 +590,7 @@ QString QStandardPaths::displayName(StandardLocation type)
 /*!
   \fn void QStandardPaths::setTestModeEnabled(bool testMode)
 
-  If \a testMode is true, this enables a special "test mode" in
+  \include standardpath/functiondoc.qdocinc setTestModeEnabled
-  QStandardPaths, which changes writable locations
-  to point to test directories, in order to prevent auto tests from reading from
-  or writing to the current user's configuration.
-
-  This affects the locations into which test programs might write files:
-  GenericDataLocation, DataLocation, ConfigLocation, GenericConfigLocation,
-  AppConfigLocation, GenericCacheLocation, CacheLocation.
-  Other locations are not affected.
-
-  On Unix, \c XDG_DATA_HOME is set to \e ~/.qttest/share, \c XDG_CONFIG_HOME is
-  set to \e ~/.qttest/config, and \c XDG_CACHE_HOME is set to \e ~/.qttest/cache.
-
-  On \macos, data goes to \e ~/.qttest/Application Support, cache goes to
-  \e ~/.qttest/Cache, and config goes to \e ~/.qttest/Preferences.
-
-  On Windows, everything goes to a "qttest" directory under Application Data.
 */
 
 static bool qsp_testMode = false;