Update qt_policy and add documentation

- If no version specified, policy version is set to 6.0.0, therefore
  warnings will be shown, encouraging users to set a policy.
- Update qt_policy() documentation
- Update qt_standard_project_setup() documentation
- Update the policy warning message
- Added the missing comment to clarify the extra_code region

Pick-to: 6.5
Task-number: QTBUG-96233
Change-Id: I8358fdeb880a34c96f13fc2a6cbef6afe048c4d6
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

cmake/QtCMakePackageVersionFile.cmake.in

@@ -8,7 +8,9 @@ if(QT_NO_PACKAGE_VERSION_CHECK)
     set(__qt_disable_package_version_check TRUE)
 endif()
 
+# Extra CMake code begin
 @extra_code@
+# Extra CMake code end
 
 if((NOT PACKAGE_VERSION_COMPATIBLE) OR PACKAGE_VERSION_UNSUITABLE)
     set(__qt_package_version_incompatible TRUE)

src/corelib/Qt6CoreMacros.cmake

@@ -2707,11 +2707,9 @@ function(__qt_internal_setup_policy policy sinceversion policyexplanation)
         set(__QT_INTERNAL_POLICY_${policy} "NEW" PARENT_SCOPE)
     elseif(NOT "${QT_NO_SHOW_OLD_POLICY_WARNINGS}")
         message(AUTHOR_WARNING
-            "Qt policy ${policy} is not set. "
-            "Use the qt6_set_policy command to set it and suppress this warning. "
-            "You can also silence all policy warnings by setting QT_NO_SHOW_OLD_POLICY_WARNINGS "
-            "to true.\n"
+            "Qt policy ${policy} is not set: "
             "${policyexplanation} "
+            "Use the qt_policy command to set the policy and suppress this warning.\n"
         )
     endif()
 endfunction()
@@ -2741,6 +2739,7 @@ macro(qt6_standard_project_setup)
             message(FATAL_ERROR "Unexpected arguments: ${arg_UNPARSED_ARGUMENTS}")
         endif()
 
+        # Set the Qt CMake policy based on the requested version(s)
         set(__qt_policy_check_version "6.0.0")
         if(Qt6_VERSION_MAJOR)
             set(__qt_current_version
@@ -2753,15 +2752,21 @@ macro(qt6_standard_project_setup)
         endif()
         if(__qt_sps_arg_MIN_VERSION)
             if("${__qt_current_version}" VERSION_LESS "${__qt_sps_arg_MIN_VERSION}")
-                message(FATAL_ERROR "Project required a Qt minimum version of ${__qt_sps_arg_MIN_VERSION}, but current version is only ${__qt_current_version}")
+                message(FATAL_ERROR
+                    "Project required a Qt minimum version of ${__qt_sps_arg_MIN_VERSION}, "
+                    "but current version is only ${__qt_current_version}.")
             endif()
             set(__qt_policy_check_version "${__qt_sps_arg_MIN_VERSION}")
         endif()
         if(__qt_sps_arg_MAX_VERSION)
+            if(__qt_sps_arg_MIN_VERSION)
                 if(${__qt_sps_arg_MAX_VERSION} VERSION_LESS ${__qt_sps_arg_MIN_VERSION})
-                message(FATAL_ERROR "MAX_VERSION must be larger or equal than MIN_VERSION")
+                    message(FATAL_ERROR "MAX_VERSION must be larger than or equal to MIN_VERSION.")
                 endif()
                 set(__qt_policy_check_version "${__qt_sps_arg_MAX_VERSION}")
+            else()
+                message(FATAL_ERROR "Please specify the MIN_VERSION as well.")
+            endif()
         endif()
 
         # All changes below this point should not result in a change to an

src/corelib/doc/src/cmake/qt_policy.qdoc

@@ -18,35 +18,49 @@
 
 \badcode
 qt_policy(
-    [SET policy behavior]
-    [GET policy variable]
+    [SET <policy_name> behavior]
+    [GET <policy_name> <variable>]
 )
 \endcode
 
 \versionlessCMakeCommandsNote qt6_policy()
 
 \section1 Description
+
 This command has two modes:
+
 \list
 \li When the \c{SET} keyword is used, this command can be used to opt in to
     behavior changes in Qt's CMake API, or to explicitly opt out of them.
-\li When the \c{GET} keyword is used, \c{variable} is set to the current
-    value for the policy.
+\li When the \c{GET} keyword is used, \c{<variable>} is set to the current
+    behavior for the policy, i.e. \c OLD or \c NEW.
 \endlist
-\c{policyname} must be the name of a Qt cmake policy. Using an unknown policy
-is an error; code supporting older Qt versions should check with
+
+\c{<policy_name>} must be the name of one of the \l{Qt CMake policies}.
+Policy names have the form of \c{QTP<NNNN>} where <NNNN> is
+an integer specifying the index of the policy. Using an invalid policy
+name results in an error.
+
+Code supporting older Qt versions can check the existence of a policy by
+checking the value of the \c{QT_KNOWN_POLICY_<policy_name>} variable before
+getting the value of \c <policy_name> or setting its behavior.
+
 \badcode
 if(QT_KNOWN_POLICY_<policy_name>)
+    qt_policy(SET <policy_name> NEW)
+endif()
 \endcode
-whether the policy exists before querying or setting it.
 
-\c{behavior} can
-either be
+You can set \c behavior to one of the following options:
+
 \list
-\li \c{NEW} to opt into the new behavior, or
-\li \c{OLD} to explicitly opt-out of it.
+\li \c{NEW} to opt into the new behavior
+\li \c{OLD} to explicitly opt-out of it
 \endlist
 
+\note The \c{OLD} behavior of a policy is deprecated, and may
+be removed in the future.
+
 \sa qt_standard_project_setup
 
 */

src/corelib/doc/src/cmake/qt_standard_project_setup.qdoc

@@ -18,8 +18,8 @@
 
 \badcode
 qt_standard_project_setup(
-    [MIN_VERSION policy_min]
-    [MAX_VERSION policy_max]
+    [MIN_VERSION <version>]
+    [MAX_VERSION <version>]
 )
 \endcode
 
@@ -50,15 +50,14 @@ have been defined. It does the following things:
     Qt-internal targets in this folder.
 \endlist
 
-Moreover, since Qt 6.5 it can be used to change the default behavior of Qt's CMake
-API, by opting in to changes from newer Qt versions. If \c{MIN_VERSION} is
+Since Qt 6.5, it is possible to change the default behavior of Qt's CMake
+API by opting in to changes from newer Qt versions. If \c{MIN_VERSION} is
 specified, all suggested changes introduced in Qt up to \c{MIN_VERSION} are enabled,
 and using an older Qt version will result in an error.
 If additionally \c{MAX_VERSION} has been specified, any new changes introduced
 in versions up to \c{MAX_VERSION} are also enabled (but using an older Qt
-version is not an error).
-This is similar to CMake's policy concept (compare \l{cmake_policy}).
-
+version is not an error). This is similar to CMake's policy concept
+(compare \l{cmake_policy}).
 
 On platforms that support \c{RPATH} (other than Apple platforms), two values
 are appended to the \c{CMAKE_INSTALL_RPATH} variable by this command.