other misc fixes

[wxWidgets.git] / interface / ptr_scpd.h

diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h
index 2dfb6dc589ff7e4a9652694a551242d0bb723afe..11180b1a5565cc28350759a747102f0ed92e54dc 100644 (file)
--- a/interface/ptr_scpd.h
+++ b/interface/ptr_scpd.h
@@ -11,20 +11,82 @@
     @wxheader{ptr_scpd.h}
 
     This is a simple scoped smart pointer implementation that is similar to
     @wxheader{ptr_scpd.h}
 
     This is a simple scoped smart pointer implementation that is similar to

-    the Boost smart pointers but rewritten to
-    use macros instead.
+    the Boost smart pointers (see http://www.boost.org) but rewritten
+    to use macros instead.

 
     Since wxWidgets 2.9.0 there is also a templated version of this class
 
     Since wxWidgets 2.9.0 there is also a templated version of this class

-    with the same name. See wxScopedPtrT().
+    with the same name. See wxScopedPtr<T>.

 
     A smart pointer holds a pointer to an object. The memory used by the object is
     deleted when the smart pointer goes out of scope. This class is different from
 
     A smart pointer holds a pointer to an object. The memory used by the object is
     deleted when the smart pointer goes out of scope. This class is different from

-    the @c std::auto_ptr in so far as it doesn't provide copy constructor
+    the @c std::auto_ptr<> in so far as it doesn't provide copy constructor

     nor assignment operator. This limits what you can do with it but is much less
     surprizing than the "destructive copy" behaviour of the standard class.
 
     nor assignment operator. This limits what you can do with it but is much less
     surprizing than the "destructive copy" behaviour of the standard class.
 

+    @b Example:
+
+    Below is an example of using a wxWidgets scoped smart pointer and pointer array.
+
+    @code
+    class MyClass{ ... };
+
+    // declare a smart pointer to a MyClass called wxMyClassPtr
+    wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
+    // declare a smart pointer to an array of chars
+    wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
+
+    ...
+
+    // define the first pointer class, must be complete
+    wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
+    // define the second pointer class
+    wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
+
+    // create an object with a new pointer to MyClass
+    wxMyClassPtr theObj(new MyClass());
+    // reset the pointer (deletes the previous one)
+    theObj.reset(new MyClass());
+
+    // access the pointer
+    theObj->MyFunc();
+
+    // create an object with a new array of chars
+    wxCharArray theCharObj(new char[100]);
+
+    // access the array
+    theCharObj[0] = "!";
+    @endcode
+
+    @section wxscopedptr_newpointers Declaring new smart pointer types
+
+    To declare the smart pointer class @c CLASSNAME containing pointes to
+    a (possibly incomplete) type @c TYPE you should use
+    @code
+        wxDECLARE_SCOPED_PTR( TYPE,        // type of the values
+                              CLASSNAME ); // name of the class
+    @endcode
+    And later, when @c TYPE is fully defined, you must also use
+    @code
+        wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME );
+    @endcode
+    to implement the scoped pointer class.
+
+    The first argument of these macro is the pointer type, the second is the name
+    of the new smart pointer class being created. Below we will use wxScopedPtr
+    to represent the scoped pointer class, but the user may create the class with
+    any legal name.
+
+    Alternatively, if you don't have to separate the point of declaration and
+    definition of this class and if you accept the standard naming convention,
+    that is that the scoped pointer for the class @c Foo is called @c FooPtr,
+    you can use a single macro which replaces two macros above:
+    @code
+        wxDEFINE_SCOPED_PTR_TYPE( TYPE );
+    @endcode
+    Once again, in this cass @c CLASSNAME will be @c TYPEPtr.
+

     @library{wxbase}
     @library{wxbase}

-    @category{FIXME}
+    @category{smartpointers}

 
     @see wxScopedArray
 */
 
     @see wxScopedArray
 */


@@ -32,10 +94,11 @@ class wxScopedPtr
 {
 public:
     /**
 {
 public:
     /**

-        Creates the smart pointer with the given pointer or none if @NULL.  On
-        compilers that support it, this uses the explicit keyword.
+        Creates the smart pointer with the given pointer or none if @NULL.
+
+        On compilers that support it, this uses the explicit keyword.

     */
     */

-    explicit wxScopedPtr(type T = NULL);
+    explicit wxScopedPtr(type* T = NULL);

 
     /**
         Destructor frees the pointer help by this object if it is not @NULL.
 
     /**
         Destructor frees the pointer help by this object if it is not @NULL.


@@ -43,43 +106,51 @@ public:
     ~wxScopedPtr();
 
     /**
     ~wxScopedPtr();
 
     /**

-        This operator gets the pointer stored in the smart pointer or returns @NULL if
-        there is none.
+        This operator gets the pointer stored in the smart pointer or returns
+        @NULL if there is none.

     */
     const T* get();
 
     /**
         This operator works like the standard C++ pointer operator to return the object
     */
     const T* get();
 
     /**
         This operator works like the standard C++ pointer operator to return the object

-        being pointed to by the pointer.  If the pointer is @NULL or invalid this will
-        crash.
+        being pointed to by the pointer.
+
+        @note
+        If the pointer is @NULL or invalid this will crash.

     */
     */

-    const T operator *();
+    const T& operator *();

 
     /**
         This operator works like the standard C++ pointer operator to return the pointer
         in the smart pointer or @NULL if it is empty.
     */
 
     /**
         This operator works like the standard C++ pointer operator to return the pointer
         in the smart pointer or @NULL if it is empty.
     */

-    const T* operator -();
+    const T* operator ->();

 
     /**
         Returns the currently hold pointer and resets the smart pointer object to
 
     /**
         Returns the currently hold pointer and resets the smart pointer object to

-        @NULL. After a call to this function the caller is responsible for
-        deleting the pointer.
+        @NULL.
+
+        @remarks
+        After a call to this function the caller is responsible for deleting the
+        pointer.

     */
     T* release();
 
     /**
         Deletes the currently held pointer and sets it to @a p or to @NULL if no
     */
     T* release();
 
     /**
         Deletes the currently held pointer and sets it to @a p or to @NULL if no

-        arguments are specified. This function does check to make sure that the
-        pointer you are assigning is not the same pointer that is already stored.
+        arguments are specified.
+
+        @note
+        This function does check to make sure that the pointer you are assigning
+        is not the same pointer that is already stored.

     */
     */

-    reset(T p  = NULL);
+    reset(T* p  = NULL);

 
     /**
 
     /**

-        Swap the pointer inside the smart pointer with @e other. The pointer being
+        Swap the pointer inside the smart pointer with @a other. The pointer being

         swapped must be of the same type (hence the same class name).
     */
         swapped must be of the same type (hence the same class name).
     */

-    swap(wxScopedPtr amp; other);
+    swap(wxScopedPtr& other);

 };
 
 
 };
 
 


@@ -89,11 +160,60 @@ public:
     @wxheader{ptr_scpd.h}
 
     This is a simple scoped smart pointer array implementation that is similar to
     @wxheader{ptr_scpd.h}
 
     This is a simple scoped smart pointer array implementation that is similar to

-    the Boost smart pointers but rewritten to
+    the Boost smart pointers (see http://www.boost.org/) but rewritten to

     use macros instead.
 
     use macros instead.
 

+    @b Example:
+
+    Below is an example of using a wxWidgets scoped smart pointer and pointer array.
+
+    @code
+    class MyClass { ... };
+
+    // declare a smart pointer to a MyClass called wxMyClassPtr
+    wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
+    // declare a smart pointer to an array of chars
+    wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
+
+    ...
+
+    // define the first pointer class, must be complete
+    wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
+    // define the second pointer class
+    wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
+
+    // create an object with a new pointer to MyClass
+    wxMyClassPtr theObj(new MyClass());
+    // reset the pointer (deletes the previous one)
+    theObj.reset(new MyClass());
+
+    // access the pointer
+    theObj->MyFunc();
+
+    // create an object with a new array of chars
+    wxCharArray theCharObj(new char[100]);
+
+    // access the array
+    theCharObj[0] = "!";
+    @endcode
+
+    <b>Declaring new smart pointer types:</b>
+    @code
+    wxDECLAR_SCOPED_ARRAY( TYPE,        // type of the values
+                           CLASSNAME ); // name of the class
+    @endcode
+
+    A smart pointer holds a pointer to an object (which must be complete when
+    wxDEFINE_SCOPED_ARRAY() is called).
+
+    The memory used by the object is deleted when the smart pointer goes out of
+    scope. The first argument of the macro is the pointer type, the second is the
+    name of the new smart pointer class being created. Below we will use wxScopedArray
+    to represent the scoped pointer array class, but the user may create the class with
+    any legal name.
+

     @library{wxbase}
     @library{wxbase}

-    @category{FIXME}
+    @category{smartpointers}

 
     @see wxScopedPtr
 */
 
     @see wxScopedPtr
 */


@@ -104,7 +224,7 @@ public:
         Creates the smart pointer with the given pointer or none if @NULL.  On
         compilers that support it, this uses the explicit keyword.
     */
         Creates the smart pointer with the given pointer or none if @NULL.  On
         compilers that support it, this uses the explicit keyword.
     */

-    wxScopedArray(type T = NULL);
+    wxScopedArray(type*  T = NULL);

 
     /**
         This operator gets the pointer stored in the smart pointer or returns @NULL if
 
     /**
         This operator gets the pointer stored in the smart pointer or returns @NULL if


@@ -116,20 +236,20 @@ public:
         This operator acts like the standard [] indexing operator for C++ arrays.  The
         function does not do bounds checking.
     */
         This operator acts like the standard [] indexing operator for C++ arrays.  The
         function does not do bounds checking.
     */

-    const T operator [](long int i);
+    const T& operator [](long int i);

 
     /**
         Deletes the currently held pointer and sets it to 'p' or to @NULL if no
         arguments are specified. This function does check to make sure that the
         pointer you are assigning is not the same pointer that is already stored.
     */
 
     /**
         Deletes the currently held pointer and sets it to 'p' or to @NULL if no
         arguments are specified. This function does check to make sure that the
         pointer you are assigning is not the same pointer that is already stored.
     */

-    reset(T p  = NULL);
+    reset(T* p  = NULL);

 
     /**
 
     /**

-        Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped
+        Swap the pointer inside the smart pointer with @a ot. The pointer being swapped

         must be of the same type (hence the same class name).
     */
         must be of the same type (hence the same class name).
     */

-    swap(wxScopedPtr amp; ot);
+    swap(wxScopedPtr& ot);

 };
 
 
 };
 
 


@@ -138,24 +258,22 @@ public:
     @class wxScopedTiedPtr
     @wxheader{ptr_scpd.h}
 
     @class wxScopedTiedPtr
     @wxheader{ptr_scpd.h}
 

-    This is a variation on the topic of wxScopedPtr. This
-    class is also a smart pointer but in addition it "ties" the pointer value to
-    another variable. In other words, during the life time of this class the value
-    of that variable is set to be the same as the value of the pointer itself and
-    it is reset to its old value when the object is destroyed. This class is
-    especially useful when converting the existing code (which may already store
-    the pointers value in some variable) to the smart pointers.
+    This is a variation on the topic of wxScopedPtr. This class is also a smart pointer
+    but in addition it "ties" the pointer value to another variable. In other words,
+    during the life time of this class the value of that variable is set to be the same
+    as the value of the pointer itself and it is reset to its old value when the object
+    is destroyed. This class is especially useful when converting the existing code
+    (which may already store the pointers value in some variable) to the smart pointers.

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{smartpointers}

 */
 */

-class wxScopedTiedPtr
+class wxScopedTiedPtr : public wxScopedPtr

 {
 public:
     /**
         Constructor creates a smart pointer initialized with @a ptr and stores
 {
 public:
     /**
         Constructor creates a smart pointer initialized with @a ptr and stores

-        @a ptr in the location specified by @a ppTie which must not be
-        @NULL.
+        @a ptr in the location specified by @a ppTie which must not be @NULL.

     */
     wxScopedTiedPtr(T** ppTie, T* ptr);
 
     */
     wxScopedTiedPtr(T** ppTie, T* ptr);
 


@@ -163,9 +281,10 @@ public:
         Destructor frees the pointer help by this object and restores the value stored
         at the tied location (as specified in the @ref ctor() constructor)
         to the old value.
         Destructor frees the pointer help by this object and restores the value stored
         at the tied location (as specified in the @ref ctor() constructor)
         to the old value.

-        Warning: this location may now contain an uninitialized value if it hadn't been
-        initialized previously, in particular don't count on it magically being
-        @NULL!
+
+        @warning
+        This location may now contain an uninitialized value if it hadn't been
+        initialized previously, in particular don't count on it magically being @NULL!

     */
     ~wxScopedTiedPtr();
 };
     */
     ~wxScopedTiedPtr();
 };


@@ -176,12 +295,12 @@ public:
     @wxheader{ptr_scpd.h}
 
     A scoped pointer template class. It is the template version of
     @wxheader{ptr_scpd.h}
 
     A scoped pointer template class. It is the template version of

-    the old-style @ref overview_wxscopedptr "scoped pointer macros".
+    the old-style @ref classwx_scoped_ptr "scoped pointer macros".

 
     @library{wxbase}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{smartpointers}

 
 

-    @see wxSharedPtr, wxWeakRef
+    @see wxSharedPtr<T>, wxWeakRef<T>

 */
 template<typename T>
 class wxScopedPtr<T>
 */
 template<typename T>
 class wxScopedPtr<T>


@@ -204,15 +323,19 @@ public:
 
     /**
         Conversion to a boolean expression (in a variant which is not
 
     /**
         Conversion to a boolean expression (in a variant which is not

-        convertable to anything but a boolean expression). If this class
-        contains a valid pointer it will return @e @true, if it contains
-        a @NULL pointer it will return @e @false.
+        convertable to anything but a boolean expression).
+
+        If this class contains a valid pointer it will return @true, if it contains
+        a @NULL pointer it will return @false.

     */
     operator unspecified_bool_type() const;
 
     /**
     */
     operator unspecified_bool_type() const;
 
     /**

-        Returns a reference to the object. If the internal pointer is @NULL
-        this method will cause an assert in debug mode.
+        Returns a reference to the object.
+
+        @note
+        If the internal pointer is @NULL this method will cause an assert
+        in debug mode.

     */
     T operator*() const;
 
     */
     T operator*() const;
 


@@ -220,18 +343,20 @@ public:
         Returns pointer to object. If the pointer is @NULL this method will
         cause an assert in debug mode.
     */
         Returns pointer to object. If the pointer is @NULL this method will
         cause an assert in debug mode.
     */

-    T* operator-() const;
+    T* operator->() const;

 
     /**
         Releases the current pointer and returns it.
 
     /**
         Releases the current pointer and returns it.

+
+        @remarks

         Afterwards the caller is responsible for deleting
         the data contained in the scoped pointer before.
     */
     T* release();
 
     /**
         Afterwards the caller is responsible for deleting
         the data contained in the scoped pointer before.
     */
     T* release();
 
     /**

-        Reset pointer to the value of @e ptr. The
-        previous pointer will be deleted.
+        Reset pointer to the value of @a ptr.
+        The previous pointer will be deleted.

     */
     void reset(T* ptr = NULL);
 
     */
     void reset(T* ptr = NULL);