removed a TODO comments, it actually doesn't seem necessary to optimize the use of...

[wxWidgets.git] / interface / scopeguard.h

diff --git a/interface/scopeguard.h b/interface/scopeguard.h
index aa86b0876f50406595025adab92e4064a8f75ee0..e8c88a7989e95af1c31467fe034632de83a26742 100644 (file)
--- a/interface/scopeguard.h
+++ b/interface/scopeguard.h
@@ -1,42 +1,95 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-    // Name:        scopeguard.h
-    // Purpose:     documentation for global functions
-    // Author:      wxWidgets team
-    // RCS-ID:      $Id$
-    // Licence:     wxWindows license
-    /////////////////////////////////////////////////////////////////////////////
-    
-    //@{
+// Name:        scopeguard.h
+// 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}

 */
 */

- wxON_BLOCK_EXIT_OBJ0(obj,  method);
-     wxON_BLOCK_EXIT_OBJ1(obj,  method,  p1);
-     wxON_BLOCK_EXIT_OBJ2(obj,  method,  p1,  p2);
+#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}
+*/
+#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 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 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 macro sets a variable to the specified value on scope exit.
+
+    Example of usage:

     @code
     @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
     @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.
-    
-    @sa wxON_BLOCK_EXIT_OBJ
+
+    @see wxON_BLOCK_EXIT_OBJ0(), wxON_BLOCK_EXIT_NULL()
+
+    @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)
+

 //@}
 
 //@}