Create class documentation for QNtfsPermissionCheckGuard

...and document the related functions as well.

Fixes: QTBUG-116350
Change-Id: I038d59f6af46b29e2123bc8b6c24ff4ffea78bbf
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
(cherry picked from commit fa79b56bd82df6852aab6819dc31b359ee7b24e7)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/io/qfile.cpp

@@ -1250,6 +1250,107 @@ qint64 QFile::size() const
 */
 
 
+/*!
+    \class QNtfsPermissionCheckGuard
+    \since 6.6
+    \inmodule QtCore
+    \brief The QNtfsPermissionCheckGuard class is a RAII class to manage NTFS
+    permission checking.
+
+    \ingroup io
+
+    For performance reasons, QFile, QFileInfo, and related classes do not
+    perform full ownership and permission (ACL) checking on NTFS file systems
+    by default. During the lifetime of any instance of this class, that
+    default is overridden and advanced checking is performed. This provides
+    a safe and easy way to manage enabling and disabling this change to the
+    default behavior.
+
+    Example:
+
+    \snippet ntfsp.cpp raii
+
+    This class is available only on Windows.
+
+    \section1 qt_ntfs_permission_lookup
+
+    Prior to Qt 6.6, the user had to directly manipulate the global variable
+    \c qt_ntfs_permission_lookup. However, this was a non-atomic global
+    variable and as such it was prone to data races.
+
+    The variable \c qt_ntfs_permission_lookup is therefore deprecated since Qt
+    6.6.
+*/
+
+/*!
+    \fn QNtfsPermissionCheckGuard::QNtfsPermissionCheckGuard()
+
+    Creates a guard and calls the function qEnableNtfsPermissionChecks().
+*/
+
+/*!
+    \fn QNtfsPermissionCheckGuard::~QNtfsPermissionCheckGuard()
+
+    Destroys the guard and calls the function qDisableNtfsPermissionChecks().
+*/
+
+
+/*!
+    \fn bool qEnableNtfsPermissionChecks()
+    \since 6.6
+    \threadsafe
+    \relates QNtfsPermissionCheckGuard
+
+    Enables permission checking on NTFS file systems. Returns \c true if the check
+    was already enabled before the call to this function, meaning that there
+    are other users.
+
+    This function is only available on Windows and makes the direct
+    manipulation of \l qt_ntfs_permission_lookup obsolete.
+
+    This is a low-level function, please consider the RAII class
+    \l QNtfsPermissionCheckGuard instead.
+
+    \note The thread-safety of this function holds only as long as there are no
+    concurrent updates to \l qt_ntfs_permission_lookup.
+*/
+
+/*!
+    \fn bool qDisableNtfsPermissionChecks()
+    \since 6.6
+    \threadsafe
+    \relates QNtfsPermissionCheckGuard
+
+    Disables permission checking on NTFS file systems. Returns \c true if the
+    check is disabled, meaning that there are no more users.
+
+    This function is only available on Windows and makes the direct
+    manipulation of \l qt_ntfs_permission_lookup obsolete.
+
+    This is a low-level function and must (only) be called to match one earlier
+    call to qEnableNtfsPermissionChecks(). Please consider the RAII class
+    \l QNtfsPermissionCheckGuard instead.
+
+    \note The thread-safety of this function holds only as long as there are no
+    concurrent updates to \l qt_ntfs_permission_lookup.
+*/
+
+/*!
+    \fn bool qAreNtfsPermissionChecksEnabled()
+    \since 6.6
+    \threadsafe
+    \relates QNtfsPermissionCheckGuard
+
+    Checks the status of the permission checks on NTFS file systems. Returns
+    \c true if the check is enabled.
+
+    This function is only available on Windows and makes the direct
+    manipulation of \l qt_ntfs_permission_lookup obsolete.
+
+    \note The thread-safety of this function holds only as long as there are no
+    concurrent updates to \l qt_ntfs_permission_lookup.
+*/
+
 QT_END_NAMESPACE
 
 #ifndef QT_NO_QOBJECT

src/corelib/io/qfile.h

@@ -26,7 +26,7 @@ namespace std {
 
 QT_BEGIN_NAMESPACE
 
-#ifdef Q_OS_WIN
+#if defined(Q_OS_WIN) || defined(Q_QDOC)
 
 #if QT_DEPRECATED_SINCE(6,6)
 QT_DEPRECATED_VERSION_X_6_6("Use QNtfsPermissionCheckGuard RAII class instead.")

src/corelib/io/qfilesystemengine_win.cpp

@@ -390,12 +390,6 @@ static QBasicAtomicInt qt_ntfs_permission_lookup_v2 = Q_BASIC_ATOMIC_INITIALIZER
 QT_WARNING_PUSH
 QT_WARNING_DISABLE_DEPRECATED
 
-/*!
-    \internal
-
-    Returns true if the check was previously enabled.
-*/
-
 bool qEnableNtfsPermissionChecks() noexcept
 {
     return qt_ntfs_permission_lookup_v2.fetchAndAddRelaxed(1)
@@ -403,12 +397,6 @@ QT_IF_DEPRECATED_SINCE(6, 6, /*nothing*/, + qt_ntfs_permission_lookup)
         != 0;
 }
 
-/*!
-    \internal
-
-    Returns true if the check is disabled, i.e. there are no more users.
-*/
-
 bool qDisableNtfsPermissionChecks() noexcept
 {
     return qt_ntfs_permission_lookup_v2.fetchAndSubRelaxed(1)
@@ -416,12 +404,6 @@ QT_IF_DEPRECATED_SINCE(6, 6, /*nothing*/, + qt_ntfs_permission_lookup)
         == 1;
 }
 
-/*!
-    \internal
-
-    Returns true if the check is enabled.
-*/
-
 bool qAreNtfsPermissionChecksEnabled() noexcept
 {
     return qt_ntfs_permission_lookup_v2.loadRelaxed()