More interface header reviews by Azriel Fasten, and added skeleton docs for wxBookCtr...

[wxWidgets.git] / interface / clntdata.h

diff --git a/interface/clntdata.h b/interface/clntdata.h
index bc015c99648a04074fe510e7a6ca5be39419d789..62d7a864297a449a4c6629ec919534a970bf8439 100644 (file)
--- a/interface/clntdata.h
+++ b/interface/clntdata.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        clntdata.h
-// Purpose:     documentation for wxClientDataContainer class
+// Purpose:     interface of wxClientData[Container] and wxStringClientData
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -12,43 +12,41 @@
 
     This class is a mixin that provides storage and management of "client
     data." This data can either be of type void - in which case the data
-    @e container does not take care of freeing the data again
-    or it is of type wxClientData or its derivatives. In that case the
-    container will free the memory itself later.
-    Note that you @e must not assign both void data and data
-    derived from the wxClientData class to a container.
+    @e container does not take care of freeing the data again or it is of
+    type wxClientData or its derivatives. In that case the container will free
+    the memory itself later. Note that you @e must not assign both void data
+    and data derived from the wxClientData class to a container.
 
-    NOTE: This functionality is currently duplicated in wxEvtHandler in
-    order to avoid having more than one vtable in that class hierarchy.
+    @note This functionality is currently duplicated in wxEvtHandler in order
+          to avoid having more than one vtable in that class hierarchy.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{containers}
 
-    @seealso
-    wxEvtHandler, wxClientData
+    @see wxEvtHandler, wxClientData
 */
 class wxClientDataContainer
 {
 public:
     /**
-        
+        Default constructor.
     */
     wxClientDataContainer();
 
     /**
-        
+        Destructor.
     */
     ~wxClientDataContainer();
 
     /**
         Get the untyped client data.
     */
-    void* GetClientData();
+    void* GetClientData() const;
 
     /**
         Get a pointer to the client data object.
     */
-    wxClientData* GetClientObject();
+    wxClientData* GetClientObject() const;
 
     /**
         Set the untyped client data.
@@ -62,38 +60,35 @@ public:
 };
 
 
+
 /**
     @class wxClientData
     @wxheader{clntdata.h}
 
-    All classes deriving from wxEvtHandler
-    (such as all controls and wxApp)
-    can hold arbitrary data which is here referred to as "client data".
-    This is useful e.g. for scripting languages which need to handle
-    shadow objects for most of wxWidgets' classes and which store
-    a handle to such a shadow class as client data in that class.
-    This data can either be of type void - in which case the data
-    @e container does not take care of freeing the data again
-    or it is of type wxClientData or its derivatives. In that case the
-    container (e.g. a control) will free the memory itself later.
-    Note that you @e must not assign both void data and data
-    derived from the wxClientData class to a container.
-
-    Some controls can hold various items and these controls can
-    additionally hold client data for each item. This is the case for
-    wxChoice, wxComboBox
-    and wxListBox. wxTreeCtrl
-    has a specialized class wxTreeItemData
-    for each item in the tree.
-
-    If you want to add client data to your own classes, you may
-    use the mix-in class wxClientDataContainer.
+    All classes deriving from wxEvtHandler (such as all controls and wxApp) can
+    hold arbitrary data which is here referred to as "client data". This is
+    useful e.g. for scripting languages which need to handle shadow objects for
+    most of wxWidgets' classes and which store a handle to such a shadow class
+    as client data in that class. This data can either be of type void - in
+    which case the data @e container does not take care of freeing the data
+    again or it is of type wxClientData or its derivatives. In that case the
+    container (e.g. a control) will free the memory itself later. Note that you
+    @e must not assign both void data and data derived from the wxClientData
+    class to a container.
+
+    Some controls can hold various items and these controls can additionally
+    hold client data for each item. This is the case for wxChoice, wxComboBox
+    and wxListBox. wxTreeCtrl has a specialized class wxTreeItemData for each
+    item in the tree.
+
+    If you want to add client data to your own classes, you may use the mix-in
+    class wxClientDataContainer.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{containers}
 
-    @seealso
-    wxEvtHandler, wxTreeItemData, wxStringClientData, wxClientDataContainer
+    @see wxEvtHandler, wxTreeItemData, wxStringClientData,
+         wxClientDataContainer
 */
 class wxClientData
 {
@@ -110,6 +105,7 @@ public:
 };
 
 
+
 /**
     @class wxStringClientData
     @wxheader{clntdata.h}
@@ -117,26 +113,29 @@ public:
     Predefined client data class for holding a string.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{containers}
 */
 class wxStringClientData : public wxClientData
 {
 public:
-    //@{
     /**
-        Create client data with string.
+        Default constructor.
     */
     wxStringClientData();
+
+    /**
+        Create client data with string.
+    */
     wxStringClientData(const wxString& data);
-    //@}
 
     /**
         Get string client data.
     */
-    const wxString GetData();
+    const wxString GetData() const;
 
     /**
         Set string client data.
     */
     void SetData(const wxString& data);
 };
+