From: Robert Roebling <robert@roebling.de>
Date: Mon, 7 Apr 2008 10:37:32 +0000 (+0000)
Subject: Further corrections to container class docs
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/73473b3e8c06046b333265b3624f997f532c7fe2

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 c204429e1d..2d4246f5f1 100644
--- 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.
 
+    @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}
 
-    @see wxArray, wxVector
+    @see wxArray<T>, wxVector<T>
 */
-template<typename T>
 class wxList<T>
 {
 public:
@@ -46,15 +92,15 @@ public:
     /**
         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 ).
     */
-    ~wxList();
+    ~wxList<T>();
 
     /**
         Appends the pointer to @a object to the list.
@@ -327,9 +373,9 @@ public:
     @library{wxbase}
     @category{FIXME}
 
-    @see wxList, wxHashTable
+    @see wxList<T>, wxHashTable
 */
-class wxNode
+class wxNode<T>
 {
 public:
     /**
diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h
index 2dfb6dc589..1247b7d39f 100644
--- 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
-    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
@@ -181,7 +181,7 @@ public:
     @library{wxbase}
     @category{FIXME}
 
-    @see wxSharedPtr, wxWeakRef
+    @see wxSharedPtr<T>, wxWeakRef<T>
 */
 template<typename T>
 class wxScopedPtr<T>
diff --git a/interface/ptr_shrd.h b/interface/ptr_shrd.h
index d94a8aec27..9c7da8f830 100644
--- a/interface/ptr_shrd.h
+++ b/interface/ptr_shrd.h
@@ -16,7 +16,7 @@
     @library{wxbase}
     @category{smartpointers}
 
-    @see wxScopedPtr<T>, wxWeakRef<T>, wxObjectDataPtr
+    @see wxScopedPtr<T>, wxWeakRef<T>, wxObjectDataPtr<T>
 */
 template<typename T>
 class wxSharedPtr<T>
diff --git a/interface/weakref.h b/interface/weakref.h
index a527e1d029..f33ee60548 100644
--- a/interface/weakref.h
+++ b/interface/weakref.h
@@ -9,8 +9,8 @@
 /**
     @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).
 
@@ -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.
 
-    @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).
 
-    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}
@@ -48,17 +48,17 @@ public:
     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.
 
-    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}
 
-    @see wxSharedPtr, wxScopedPtr
+    @see wxSharedPtr<T>, wxScopedPtr<T>
 */
 template<typename T>
 class wxWeakRef<T>