Tweaked wxPGProperty::StringToValue() and IntToValue() docs

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

include/wx/propgrid/property.h

@@ -1016,9 +1016,15 @@ public:
                                 wxPGValidationInfo& validationInfo ) const;
 
     /**
-        Converts 'text' into proper value 'variant'.
+        Converts text into wxVariant value appropriate for this property.
-        Returns true if new (different than m_value) value could be interpreted
+
-        from the text.
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param text
+            Text to be translated into variant.
+
         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one (they may be different).
@@ -1026,25 +1032,36 @@ public:
             composite property string value (as generated by GetValueAsString()
             called with this same flag).
 
-        @remarks
+        @return Returns @true if resulting wxVariant value was different.
-        Default implementation converts semicolon delimited tokens into child
+
-        values. Only works for properties with children.
+        @remarks Default implementation converts semicolon delimited tokens into
+                child values. Only works for properties with children.
+
+                You might want to take into account that m_value is Null variant
+                if property value is unspecified (which is usually only case if
+                you explicitly enabled that sort behavior).
     */
     virtual bool StringToValue( wxVariant& variant,
                                 const wxString& text,
                                 int argFlags = 0 ) const;
 
     /**
-        Converts 'number' (including choice selection) into proper value
+        Converts integer (possibly a choice selection) into wxVariant value
-        'variant'.
+        appropriate for this property.
 
-        Returns true if new (different than m_value) value could be interpreted
+        @param variant
-        from the integer.
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param number
+            Integer to be translated into variant.
 
         @param argFlags
             If wxPG_FULL_VALUE is set, returns complete, storable value instead
             of displayable one.
 
+        @return Returns @true if resulting wxVariant value was different.
+
         @remarks
         - If property is not supposed to use choice or spinctrl or other editor
           with int-based value, it is not necessary to implement this method.
@@ -1052,6 +1069,9 @@ public:
         - If property uses choice control, and displays a dialog on some choice
           items, then it is preferred to display that dialog in IntToValue
           instead of OnEvent.
+        - You might want to take into account that m_value is Null variant if
+          property value is unspecified (which is usually only case if you
+          explicitly enabled that sort behavior).
     */
     virtual bool IntToValue( wxVariant& value,
                              int number,

interface/wx/propgrid/property.h

@@ -473,33 +473,60 @@ public:
     virtual bool ValidateValue( wxVariant& value, wxPGValidationInfo& validationInfo ) const;
 
     /**
-        Converts 'text' into proper value 'variant'. Returns true if new (different than
+        Converts text into wxVariant value appropriate for this property.
-        m_value) value could be interpreted from the text.
-        @param argFlags
-        If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable
-        one (they may be different).
-        If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of composite
-        property string value (as generated by GetValueAsString() called with this same
-        flag).
 
-        @remarks
+        @param variant
-        Default implementation converts semicolon delimited tokens into child values. Only
+            On function entry this is the old value (should not be wxNullVariant
-        works for properties with children.
+            in normal cases). Translated value must be assigned back to it.
+
+        @param text
+            Text to be translated into variant.
+
+        @param argFlags
+            If wxPG_FULL_VALUE is set, returns complete, storable value instead
+            of displayable one (they may be different).
+            If wxPG_COMPOSITE_FRAGMENT is set, text is interpreted as a part of
+            composite property string value (as generated by GetValueAsString()
+            called with this same flag).
+
+        @return Returns @true if resulting wxVariant value was different.
+
+        @remarks Default implementation converts semicolon delimited tokens into
+                child values. Only works for properties with children.
+
+                You might want to take into account that m_value is Null variant
+                if property value is unspecified (which is usually only case if
+                you explicitly enabled that sort behavior).
     */
     virtual bool StringToValue( wxVariant& variant, const wxString& text, int argFlags = 0 ) const;
 
     /**
-        Converts 'number' (including choice selection) into proper value 'variant'.
+        Converts integer (possibly a choice selection) into wxVariant value
-        Returns true if new (different than m_value) value could be interpreted from the integer.
+        appropriate for this property.
+
+        @param variant
+            On function entry this is the old value (should not be wxNullVariant
+            in normal cases). Translated value must be assigned back to it.
+
+        @param number
+            Integer to be translated into variant.
+
         @param argFlags
-        If wxPG_FULL_VALUE is set, returns complete, storable value instead of displayable one.
+            If wxPG_FULL_VALUE is set, returns complete, storable value instead
+            of displayable one.
+
+        @return Returns @true if resulting wxVariant value was different.
 
         @remarks
         - If property is not supposed to use choice or spinctrl or other editor
           with int-based value, it is not necessary to implement this method.
         - Default implementation simply assign given int to m_value.
-        - If property uses choice control, and displays a dialog on some choice items,
+        - If property uses choice control, and displays a dialog on some choice
-          then it is preferred to display that dialog in IntToValue instead of OnEvent.
+          items, then it is preferred to display that dialog in IntToValue
+          instead of OnEvent.
+        - You might want to take into account that m_value is Null variant if
+          property value is unspecified (which is usually only case if you
+          explicitly enabled that sort behavior).
     */
     virtual bool IntToValue( wxVariant& value, int number, int argFlags = 0 ) const;