fix various Doxygen errors (#9568)

[wxWidgets.git] / interface / scopeguard.h

diff --git a/interface/scopeguard.h b/interface/scopeguard.h
index 0d1a8b501b79385f3404ec78750fb633dc04aab5..e8c88a7989e95af1c31467fe034632de83a26742 100644 (file)
--- a/interface/scopeguard.h
+++ b/interface/scopeguard.h
@@ -1,42 +1,95 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        scopeguard.h
-// Purpose:     documentation for global functions
+// Purpose:     interface of global functions
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/** @ingroup group_funcmacro_misc */
 //@{
 /**
-    This family of macros is similar to wxON_BLOCK_EXIT
-    but calls a method of the given object instead of a free function.
+    This macro ensures that the global @a function with 0, 1, 2 or more
+    parameters (up to some implementation-defined limit) is executed on scope
+    exit, whether due to a normal function return or because an exception has
+    been thrown. A typical example of its usage:
+
+    @code
+    void *buf = malloc(size);
+    wxON_BLOCK_EXIT1(free, buf);
+    @endcode
+
+    Please see the original article by Andrei Alexandrescu and Petru Marginean
+    published in December 2000 issue of C/C++ Users Journal for more details.
+
+    @see wxON_BLOCK_EXIT_OBJ0()
+
+    @header{wx/scopeguard.h}
+*/
+#define wxON_BLOCK_EXIT0(function)
+#define wxON_BLOCK_EXIT1(function, p1)
+#define wxON_BLOCK_EXIT2(function, p1, p2)
+//@}
+
+/** @ingroup group_funcmacro_misc */
+//@{
+/**
+    This family of macros is similar to wxON_BLOCK_EXIT0(), but calls a method
+    of the given object instead of a free function.
+
+    @header{wx/scopeguard.h}
 */
-wxON_BLOCK_EXIT_OBJ0(obj,  method);
-wxON_BLOCK_EXIT_OBJ1(obj,  method,  p1);
-wxON_BLOCK_EXIT_OBJ2(obj,  method,  p1,  p2);
+#define wxON_BLOCK_EXIT_OBJ0(object, method)
+#define wxON_BLOCK_EXIT_OBJ1(object, method, p1)
+#define wxON_BLOCK_EXIT_OBJ2(object, method, p1, p2)
 //@}
 
+/** @ingroup group_funcmacro_misc */
+//@{
+/**
+    This family of macros is similar to wxON_BLOCK_OBJ0(), but calls a method
+    of @c this object instead of a method of the specified object.
 
+    @header{wx/scopeguard.h}
+*/
+#define wxON_BLOCK_EXIT_THIS0(method)
+#define wxON_BLOCK_EXIT_THIS1(method, p1)
+#define wxON_BLOCK_EXIT_THIS2(method, p1, p2)
+//@}
+
+/** @ingroup group_funcmacro_misc */
 //@{
 /**
-    This family of macros allows to ensure that the global function @e func
-    with 0, 1, 2 or more parameters (up to some implementaton-defined limit) is
-    executed on scope exit, whether due to a normal function return or because an
-    exception has been thrown. A typical example of its usage:
+    This macro sets a variable to the specified value on scope exit.
 
+    Example of usage:
     @code
-    void *buf = malloc(size);
-        wxON_BLOCK_EXIT1(free, buf);
+    void foo()
+    {
+        bool isDoingSomething = true;
+        {
+            wxON_BLOCK_EXIT_SET(isDoingSomething, false);
+            ... do something ...
+        }
+        ... isDoingSomething is false now ...
+    }
     @endcode
 
-    Please see the original article by Andrei Alexandrescu and Petru Marginean
-    published in December 2000 issue of C/C++ Users Journal for more
-    details.
+    @see wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL()
 
-    @sa wxON_BLOCK_EXIT_OBJ
+    @header{wx/scopeguard.h}
 */
-wxON_BLOCK_EXIT0(func);
-wxON_BLOCK_EXIT1(func,  p1);
-wxON_BLOCK_EXIT2(func,  p1,  p2);
+#define wxON_BLOCK_EXIT_SET(var, value)
+
+/**
+    This macro sets the pointer passed to it as argument to NULL on scope exit.
+
+    It must be used instead of wxON_BLOCK_EXIT_SET() when the value being set
+    is @c NULL.
+
+    @header{wx/scopeguard.h}
+ */
+#define wxON_BLOCK_EXIT_NULL(ptr)
+
 //@}