QScopeGuard: Make constructor public

With Class Template Argument Deduction users might want to use the constructor
itself instead of a separate helper function. In both cases it's possible to let
the compiler deduce the template arguments.

Try to make the usefulness of the helper function in the absence of CTAD still
clear in the documentation.

Change-Id: I9b07983c1fb276a6dd9e7ed4c3e606764e9b68ca
Reviewed-by: Ville Voutilainen <ville.voutilainen@qt.io>

2 files changed, 55 insertions, 23 deletions

diff --git a/src/corelib/tools/qscopeguard.h b/src/corelib/tools/qscopeguard.h
index 40d2747b1d..4d2e715df1 100644
--- a/src/corelib/tools/qscopeguard.h
+++ b/src/corelib/tools/qscopeguard.h
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Sérgio Martins <sergio.martins@kdab.com>
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtCore module of the Qt Toolkit.
@@ -45,10 +46,6 @@
 
 QT_BEGIN_NAMESPACE
 
-
-template <typename F> class QScopeGuard;
-template <typename F> QScopeGuard<F> qScopeGuard(F f);
-
 template <typename F>
 class
 #if __has_cpp_attribute(nodiscard)
@@ -59,13 +56,23 @@ Q_REQUIRED_RESULT
 QScopeGuard
 {
 public:
+    explicit QScopeGuard(F &&f) noexcept
+        : m_func(std::move(f))
+    {
+    }
+
+    explicit QScopeGuard(const F &f) noexcept
+        : m_func(f)
+    {
+    }
+
     QScopeGuard(QScopeGuard &&other) noexcept
         : m_func(std::move(other.m_func))
         , m_invoke(qExchange(other.m_invoke, false))
     {
     }
 
-    ~QScopeGuard()
+    ~QScopeGuard() noexcept
     {
         if (m_invoke)
             m_func();
@@ -77,28 +84,34 @@ public:
     }
 
 private:
-    explicit QScopeGuard(F &&f) noexcept
-        : m_func(std::move(f))
-    {
-    }
-
     Q_DISABLE_COPY(QScopeGuard)
 
     F m_func;
     bool m_invoke = true;
-    friend QScopeGuard qScopeGuard<F>(F);
 };
 
+#ifdef __cpp_deduction_guides
+template <typename F> QScopeGuard(F(&)()) -> QScopeGuard<F(*)()>;
+#endif
 
 template <typename F>
 #if __has_cpp_attribute(nodiscard)
 Q_REQUIRED_RESULT
 #endif
-QScopeGuard<F> qScopeGuard(F f)
+QScopeGuard<F> qScopeGuard(F &&f)
 {
     return QScopeGuard<F>(std::move(f));
 }
 
+template <typename F>
+#if __has_cpp_attribute(nodiscard)
+Q_REQUIRED_RESULT
+#endif
+QScopeGuard<F> qScopeGuard(const F &f)
+{
+    return QScopeGuard<F>(f);
+}
+
 QT_END_NAMESPACE
 
 #endif // QSCOPEGUARD_H
diff --git a/src/corelib/tools/qscopeguard.qdoc b/src/corelib/tools/qscopeguard.qdoc
index 6b3c942e84..572934d890 100644
--- a/src/corelib/tools/qscopeguard.qdoc
+++ b/src/corelib/tools/qscopeguard.qdoc
@@ -1,6 +1,7 @@
 /****************************************************************************
 **
 ** Copyright (C) 2018 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Sérgio Martins <sergio.martins@kdab.com>
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -35,6 +36,30 @@ QT_BEGIN_NAMESPACE
     \inmodule QtCore
     \brief Provides a scope guard for calling a function at the end of
            a scope.
+
+    QScopeGuard<F> is a class of which the sole purpose is to run the function
+    \a f in its destructor. This is useful for guaranteeing
+    your cleanup code is executed, whether the function is exited normally,
+    exited early by a return statement, or exited by an exception.
+
+    \note Exceptions are not supported. The callable shouldn't throw when
+          executed, copied or moved.
+
+    \sa QScopedValueRollback
+*/
+
+/*!
+    \fn template <typename F> QScopeGuard<F>::QScopeGuard(F &&f)
+    \fn template <typename F> QScopeGuard<F>::QScopeGuard(const F &f)
+
+    Create a scope guard that will execute \a f at the end of the scope.
+
+    If \e F is a lambda, its type cannot be written. In that case you need to
+    either rely on class template argument deduction (C++17 feature) and leave
+    the template parameter out completely or use the helper function
+    qScopeGuard() instead of this constructor.
+
+    \since 5.15
 */
 
 /*! \fn template <typename F> void QScopeGuard<F>::dismiss()
@@ -51,23 +76,17 @@ QT_BEGIN_NAMESPACE
            of the scope.
     \ingroup misc
 
-    QScopeGuard<F> is a class of which the sole purpose is to run the function
-    \a f in its destructor. This is useful for guaranteeing
-    your cleanup code is executed, whether the function is exited normally,
-    exited early by a return statement, or exited by an exception.
+    Create a scope guard that will execute \a f at the end of the scope.
 
-    If \e F is a lambda then you cannot instantiate the template directly,
-    therefore the qScopeGuard() helper is provided and QScopeGuard<F> is made a
-    private implementation detail.
+    This helper function is provided so that you can easily construct a
+    QScopeGuard without having to name the template parameter for the type of
+    the callable. If \e F is a lambda then you cannot write its type and relying
+    on this helper or class template argument deduction is necessary.
 
     Example usage is as follows:
 
     \snippet code/src_corelib_tools_qscopeguard.cpp 0
 
-    \note Exceptions are not supported. The callable shouldn't throw when
-          executed, copied or moved.
-
-    \sa QScopedValueRollback
 */
 
 QT_END_NAMESPACE