Further corrections to container class docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53078 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/interface/list.h b/interface/list.h
index c204429e1dbaccaa0289b0d11a813e8e9311c58f..2d4246f5f13d057b52ce6f540e805e4b1017a9cf 100644 (file)
--- a/interface/list.h
+++ b/interface/list.h
@@ -33,12 +33,58 @@
     then wxList<T> will actually derive from std::list and just add a legacy
     compatibility layer for the old wxList class.
 
     then wxList<T> will actually derive from std::list and just add a legacy
     compatibility layer for the old wxList class.
 

+    @code
+    // this part might be in a header or source (.cpp) file
+    class MyListElement
+    {
+        ... // whatever
+    };
+
+    // this macro declares and partly implements MyList class
+    WX_DECLARE_LIST(MyListElement, MyList);
+
+    ...
+
+    // the only requirement for the rest is to be AFTER the full declaration of
+    // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
+    // usually it will be found in the source file and not in the header
+
+    #include <wx/listimpl.cpp>
+    WX_DEFINE_LIST(MyList);
+
+
+    MyList list;
+    MyListElement element;
+    list.Append(&element);     // ok
+    list.Append(17);           // error: incorrect type
+
+    // let's iterate over the list in STL syntax
+    MyList::iterator iter;
+    for (iter = list.begin(); iter != list.end(); ++iter)
+    {
+        MyListElement *current = *iter;
+
+        ...process the current element...
+    }
+
+    // the same with the legacy API from the old wxList class
+    MyList::compatibility_iterator node = list.GetFirst();
+    while (node)
+    {
+        MyListElement *current = node->GetData();
+
+        ...process the current element...
+        
+        node = node->GetNext();
+    }
+    @endcode
+
+

     @library{wxbase}
     @category{FIXME}
 
     @library{wxbase}
     @category{FIXME}
 

-    @see wxArray, wxVector
+    @see wxArray<T>, wxVector<T>

 */
 */

-template<typename T>

 class wxList<T>
 {
 public:
 class wxList<T>
 {
 public:


@@ -46,15 +92,15 @@ public:
     /**
         Constructors.
     */
     /**
         Constructors.
     */

-    wxList();
-    wxList(size_t count, T* elements[]);
+    wxList<T>();
+    wxList<T>(size_t count, T* elements[]);

     //@}
 
     /**
         Destroys the list, but does not delete the objects stored in the list
         unless you called DeleteContents(@true ).
     */
     //@}
 
     /**
         Destroys the list, but does not delete the objects stored in the list
         unless you called DeleteContents(@true ).
     */

-    ~wxList();
+    ~wxList<T>();

 
     /**
         Appends the pointer to @a object to the list.
 
     /**
         Appends the pointer to @a object to the list.


@@ -327,9 +373,9 @@ public:
     @library{wxbase}
     @category{FIXME}
 
     @library{wxbase}
     @category{FIXME}
 

-    @see wxList, wxHashTable
+    @see wxList<T>, wxHashTable

 */
 */

-class wxNode
+class wxNode<T>

 {
 public:
     /**
 {
 public:
     /**

diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h
index 2dfb6dc589ff7e4a9652694a551242d0bb723afe..1247b7d39ff99799f4fc29419770e2eed3483ad5 100644 (file)
--- a/interface/ptr_scpd.h
+++ b/interface/ptr_scpd.h
@@ -15,7 +15,7 @@
     use macros instead.
 
     Since wxWidgets 2.9.0 there is also a templated version of this class
     use macros instead.
 
     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


@@ -181,7 +181,7 @@ public:
     @library{wxbase}
     @category{FIXME}
 
     @library{wxbase}
     @category{FIXME}
 

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

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

diff --git a/interface/ptr_shrd.h b/interface/ptr_shrd.h
index d94a8aec2718591f0370f40d5871771285aa2a47..9c7da8f8301c9f1f2ee0d2ddd907e0ab16752802 100644 (file)
--- a/interface/ptr_shrd.h
+++ b/interface/ptr_shrd.h
@@ -16,7 +16,7 @@
     @library{wxbase}
     @category{smartpointers}
 
     @library{wxbase}
     @category{smartpointers}
 

-    @see wxScopedPtr<T>, wxWeakRef<T>, wxObjectDataPtr
+    @see wxScopedPtr<T>, wxWeakRef<T>, wxObjectDataPtr<T>

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

diff --git a/interface/weakref.h b/interface/weakref.h
index a527e1d029c423fe1648cb34b3b019b8365bdfdd..f33ee605487acfc4bab26246beb304b2beed5ce9 100644 (file)
--- a/interface/weakref.h
+++ b/interface/weakref.h
@@ -9,8 +9,8 @@
 /**
     @wxheader{weakref.h}
 
 /**
     @wxheader{weakref.h}
 

-    wxWeakRefDynamicT is a template class for weak references that is used in
-    the same way as wxWeakRefT. The only difference is that wxWeakRefDynamic
+    wxWeakRefDynamic<T> is a template class for weak references that is used in
+    the same way as wxWeakRef<T>. The only difference is that wxWeakRefDynamic

     defaults to using @c dynamic_cast for establishing the object
     reference (while wxWeakRef defaults to @c static_cast).
 
     defaults to using @c dynamic_cast for establishing the object
     reference (while wxWeakRef defaults to @c static_cast).
 


@@ -18,14 +18,14 @@
     have a little better run-time performance. The role of wxWeakRefDynamic
     is to handle objects which derived type one does not know.
 
     have a little better run-time performance. The role of wxWeakRefDynamic
     is to handle objects which derived type one does not know.
 

-    @note wxWeakRefT selects an implementation based on the static type
+    @note wxWeakRef<T> selects an implementation based on the static type

     of T. If T does not have wxTrackable statically, it defaults to to a mixed-
     mode operation, where it uses @c dynamic_cast as the last measure (if
     available from the compiler and enabled when building wxWidgets).
 
     of T. If T does not have wxTrackable statically, it defaults to to a mixed-
     mode operation, where it uses @c dynamic_cast as the last measure (if
     available from the compiler and enabled when building wxWidgets).
 

-    For general cases, wxWeakRefT is the better choice.
+    For general cases, wxWeakRef<T> is the better choice.

 
 

-    For API documentation, see: wxWeakRef
+    For API documentation, see: wxWeakRef<T>

 
     @library{wxcore}
     @category{FIXME}
 
     @library{wxcore}
     @category{FIXME}


@@ -48,17 +48,17 @@ public:
     pointer, but when the object pointed is destroyed, the weak reference is
     automatically reset to a @NULL pointer.
 
     pointer, but when the object pointed is destroyed, the weak reference is
     automatically reset to a @NULL pointer.
 

-    wxWeakRefT can be used whenever one must keep a pointer to an object
+    wxWeakRef<T> can be used whenever one must keep a pointer to an object

     that one does not directly own, and that may be destroyed before the object
     holding the reference.
 
     that one does not directly own, and that may be destroyed before the object
     holding the reference.
 

-    wxWeakRefT is a small object and the mechanism behind it is fast
+    wxWeakRef<T> is a small object and the mechanism behind it is fast

     (@b O(1)). So the overall cost of using it is small.
 
     @library{wxbase}
     @category{FIXME}
 
     (@b O(1)). So the overall cost of using it is small.
 
     @library{wxbase}
     @category{FIXME}
 

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

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