Improve wxAutomationObject-related documentation

interface/wx/msw/ole/automtn.h

@@ -42,7 +42,7 @@ enum wxAutomationInstanceFlags
 };
 
 /**
-    Flags used for conversions between wxVariant and OLE VARIANT.
+    Flags used for conversions between wxVariant and OLE @c VARIANT.
 
     These flags are used by wxAutomationObject for its wxConvertOleToVariant()
     calls. They can be obtained by wxAutomationObject::GetConvertVariantFlags()
@@ -60,7 +60,7 @@ enum wxOleConvertVariantFlags
     wxOleConvertVariant_Default = 0,
 
     /**
-        If this flag is used, SAFEARRAYs contained in OLE VARIANTs will be
+        If this flag is used, SAFEARRAYs contained in OLE @c VARIANTs will be
         returned as wxVariants with wxVariantDataSafeArray type instead of
         wxVariants with the list type containing the (flattened) SAFEARRAY's
         elements.
@@ -72,13 +72,13 @@ enum wxOleConvertVariantFlags
 /**
     @class wxVariantDataCurrency
 
-    This class represents a thin wrapper for Microsoft Windows CURRENCY type.
+    This class represents a thin wrapper for Microsoft Windows @c CURRENCY type.
 
-    It is used for converting between wxVariant and OLE VARIANT
+    It is used for converting between wxVariant and OLE @c VARIANT
-    with type set to VT_CURRENCY. When wxVariant stores
+    with type set to @c VT_CURRENCY. When wxVariant stores
     wxVariantDataCurrency, it returns "currency" as its type.
 
-    An example of setting and getting CURRENCY value to and from wxVariant:
+    An example of setting and getting @c CURRENCY value to and from wxVariant:
     @code
     CURRENCY cy;
     wxVariant variant;
@@ -137,7 +137,7 @@ public:
     void SetValue(CURRENCY value);
 
     /**
-        Returns true if @a data is of wxVariantDataCurency type
+        Returns @true if @a data is of wxVariantDataCurency type
         and contains the same CURRENCY value.
     */
     virtual bool Eq(wxVariantData& data) const;
@@ -171,14 +171,14 @@ public:
 /**
     @class wxVariantDataErrorCode
 
-    This class represents a thin wrapper for Microsoft Windows SCODE type
+    This class represents a thin wrapper for Microsoft Windows @c SCODE type
-    (which is the same as HRESULT).
+    (which is the same as @c HRESULT).
 
-    It is used for converting between a wxVariant and OLE VARIANT with type set
+    It is used for converting between a wxVariant and OLE @c VARIANT with type set
-    to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
+    to @c VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
     "errorcode" as its type. This class can be used for returning error codes
     of automation calls or exchanging values with other applications: e.g.
-    Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with
+    Microsoft Excel returns VARIANTs with @c VT_ERROR type for cell values with
     errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
     there) etc. See wxVariantDataCurrency for an example of how to  exchange
     values between wxVariant and a native type not directly supported by it.
@@ -197,13 +197,13 @@ class wxVariantDataErrorCode : public wxVariantData
 {
 public:
     /**
-        Constructor initializes the object to @a value or S_OK if no value was
+        Constructor initializes the object to @a value or @c S_OK if no value was
         passed.
     */
     wxVariantDataErrorCode(SCODE value = S_OK);
 
     /**
-        Returns the stored SCODE value.
+        Returns the stored @c SCODE value.
     */
     SCODE GetValue() const;
 
@@ -213,8 +213,8 @@ public:
     void SetValue(SCODE value);
 
     /**
-        Returns true if @a data is of wxVariantDataErrorCode type
+        Returns @true if @a data is of wxVariantDataErrorCode type
-        and contains the same SCODE value.
+        and contains the same @c SCODE value.
     */
     virtual bool Eq(wxVariantData& data) const;
 
@@ -245,19 +245,19 @@ public:
 /**
     @class wxVariantDataSafeArray
 
-    This class represents a thin wrapper for Microsoft Windows SAFEARRAY type.
+    This class represents a thin wrapper for Microsoft Windows @c SAFEARRAY type.
 
-    It is used for converting between wxVariant and OLE VARIANT
+    It is used for converting between wxVariant and OLE @c VARIANT
-    with type set to VT_ARRAY, which has more than one dimension.
+    with type set to @c VT_ARRAY, which has more than one dimension.
     When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type.
 
-    wxVariantDataSafeArray does NOT manage the SAFEARRAY it points to.
+    wxVariantDataSafeArray does NOT manage the @c SAFEARRAY it points to.
     If you want to pass it to a wxAutomationObject as a parameter:
-        -# Assign a SAFEARRAY pointer to it and store it in a wxVariant.
+        -# Assign a @c SAFEARRAY pointer to it and store it in a wxVariant.
         -# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke())
         -# wxAutomationObject will destroy the array after the approapriate automation call.
 
-    An example of creating a 2-dimensional SAFEARRAY containing VARIANTs
+    An example of creating a 2-dimensional @c SAFEARRAY containing VARIANTs
     and storing it in a wxVariant
     @code
     SAFEARRAYBOUND bounds[2]; // 2 dimensions
@@ -341,7 +341,7 @@ public:
     void SetValue(SAFEARRAY* value);
 
     /**
-        Returns true if @a data is of wxVariantDataSafeArray type
+        Returns @true if @a data is of wxVariantDataSafeArray type
         and contains the same SAFEARRAY* value.
     */
     virtual bool Eq(wxVariantData& data) const;
@@ -375,7 +375,7 @@ public:
 
     The @b wxAutomationObject class represents an OLE automation object containing
     a single data member,
-    an IDispatch pointer. It contains a number of functions that make it easy to
+    an @c IDispatch pointer. It contains a number of functions that make it easy to
     perform
     automation operations, and set and get properties. The class makes heavy use of
     the wxVariant class.
@@ -384,11 +384,12 @@ public:
     Basic. The API is
     high-level, and the application can specify multiple properties in a single
     string. The following example
-    gets the current Excel instance, and if it exists, makes the active cell bold.
+    gets the current Microsoft Excel instance, and if it exists, makes the active cell bold.
 
     @code
     wxAutomationObject excelObject;
-      if (excelObject.GetInstance("Excel.Application"))
+    
+    if ( excelObject.GetInstance("Excel.Application") )
         excelObject.PutProperty("ActiveCell.Font.Bold", true);
     @endcode
 
@@ -405,14 +406,14 @@ class wxAutomationObject : public wxObject
 {
 public:
     /**
-        Constructor, taking an optional IDispatch pointer which will be released when
+        Constructor, taking an optional @c IDispatch pointer which will be released when
         the
         object is deleted.
     */
     wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
 
     /**
-        Destructor. If the internal IDispatch pointer is non-null, it will be released.
+        Destructor. If the internal @c IDispatch pointer is non-null, it will be released.
     */
     ~wxAutomationObject();
 
@@ -427,11 +428,18 @@ public:
         data types, and C++ provides temporary objects automatically, both of the
         following lines
         are syntactically valid:
+        @code
+        wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4));
+        wxVariant res = obj.CallMethod("Sum", 1.2, 3.4);
+        @endcode
 
         Note that @a method can contain dot-separated property names, to save the
         application
-        needing to call GetProperty several times using several temporary objects. For
+        needing to call GetProperty() several times using several temporary objects. For
         example:
+        @code
+        object.CallMethod("ActiveWorkbook.ActiveSheet.Protect", "MyPassword");
+        @endcode
     */
     wxVariant CallMethod(const wxString& method, int noArgs,
                          wxVariant args[]) const;
@@ -439,7 +447,7 @@ public:
     //@}
 
     /**
-        Creates a new object based on the ProgID, returning @true if the object was
+        Creates a new object based on the @a progID, returning @true if the object was
         successfully created,
         or @false if not.
     */
@@ -449,14 +457,14 @@ public:
         Checks if the object is in a valid state.
 
         Returns @true if the object was successfully initialized or @false if
-        it has no valid IDispatch pointer.
+        it has no valid @c IDispatch pointer.
 
-        @see GetDispatchPtr()
+        @see GetDispatchPtr(), GetInstance()
      */
     bool IsOk() const;
 
     /**
-        Gets the IDispatch pointer.
+        Gets the @c IDispatch pointer.
 
         Notice that the return value of this function is an untyped pointer but
         it can be safely cast to @c IDispatch.
@@ -465,13 +473,13 @@ public:
 
     /**
         Retrieves the current object associated with the specified ProgID, and
-        attaches the IDispatch pointer to this object.
+        attaches the @c IDispatch pointer to this object.
 
         If attaching to an existing object failed and @a flags includes
-        wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
+        ::wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
         Otherwise this function will normally log an error message which may be
         undesirable if the object may or may not exist. The
-        wxAutomationInstance_SilentIfNone flag can be used to prevent the error
+        ::wxAutomationInstance_SilentIfNone flag can be used to prevent the error
         from being logged in this case.
 
         Returns @true if a pointer was successfully retrieved, @false
@@ -479,7 +487,7 @@ public:
 
         Note that this cannot cope with two instances of a given OLE object being
         active simultaneously,
-        such as two copies of Excel running. Which object is referenced cannot
+        such as two copies of Microsoft Excel running. Which object is referenced cannot
         currently be specified.
 
         @param progId COM ProgID, e.g. "Excel.Application"
@@ -492,11 +500,11 @@ public:
     /**
         Retrieves a property from this object, assumed to be a dispatch pointer, and
         initialises @a obj with it.
-        To avoid having to deal with IDispatch pointers directly, use this function in
+        To avoid having to deal with @c IDispatch pointers directly, use this function in
         preference
         to GetProperty() when retrieving objects
         from other objects.
-        Note that an IDispatch pointer is stored as a void* pointer in wxVariant
+        Note that an @c IDispatch pointer is stored as a @c void* pointer in wxVariant
         objects.
 
         @see GetProperty()
@@ -516,6 +524,10 @@ public:
         data types, and C++ provides temporary objects automatically, both of the
         following lines
         are syntactically valid:
+        @code
+        wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
+        wxVariant res = obj.GetProperty("Range", "A1");
+        @endcode
         
         Note that @a property can contain dot-separated property names, to save the
         application
@@ -527,7 +539,7 @@ public:
     //@}
 
     /**
-        This function is a low-level implementation that allows access to the IDispatch
+        This function is a low-level implementation that allows access to the @c IDispatch
         Invoke function.
         It is not meant to be called directly by the application, but is used by other
         convenience functions.
@@ -535,8 +547,8 @@ public:
         @param member
             The member function or property name.
         @param action
-            Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
+            Bitlist: may contain @c DISPATCH_PROPERTYPUT, @c DISPATCH_PROPERTYPUTREF,
-            DISPATCH_METHOD.
+            @c DISPATCH_PROPERTYGET, @c DISPATCH_METHOD.
         @param retValue
             Return value (ignored if there is no return value)
         @param noArgs
@@ -567,10 +579,14 @@ public:
         data types, and C++ provides temporary objects automatically, both of the
         following lines
         are syntactically valid:
+        @code
+        obj.PutProperty("Value", wxVariant(23));
+        obj.PutProperty("Value", 23);
+        @endcode
 
         Note that @a property can contain dot-separated property names, to save the
         application
-        needing to call GetProperty several times using several temporary objects.
+        needing to call GetProperty() several times using several temporary objects.
     */
     bool PutProperty(const wxString& property, int noArgs,
                      wxVariant args[]);
@@ -578,41 +594,40 @@ public:
     //@}
 
     /**
-        Sets the IDispatch pointer. This function does not check if there is already an
+        Sets the @c IDispatch pointer, does not check if there is already one.
-        IDispatch pointer.
+        You may need to cast from @c IDispatch* to @c WXIDISPATCH* when calling this function.
-        You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
     */
     void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
 
     /**
         Returns the locale identifier used in automation calls.
 
-        The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by
+        The default is @c LOCALE_SYSTEM_DEFAULT but the objects obtained by
         GetObject() inherit the locale identifier from the one that created
         them.
 
         @since 2.9.5
     */
-    LCID GetLCID() const;
+    WXLCID GetLCID() const;
 
     /**
         Sets the locale identifier to be used in automation calls performed by
         this object.
 
-        The default value is LOCALE_SYSTEM_DEFAULT.
+        The default value is @c LOCALE_SYSTEM_DEFAULT.
 
         Notice that any automation objects created by this one inherit the same
-        LCID.
+        @c LCID.
 
         @since 2.9.5
     */
-    void SetLCID(LCID lcid);
+    void SetLCID(WXLCID lcid);
 
     /**
         Returns the flags used for conversions between wxVariant and OLE
-        VARIANT, see wxOleConvertVariantFlags.
+        @c VARIANT, see #wxOleConvertVariantFlags.
 
-        The default value is wxOleConvertVariant_Default for compatibility but
+        The default value is ::wxOleConvertVariant_Default for compatibility but
         it can be changed using SetConvertVariantFlags().
 
         Notice that objects obtained by GetObject() inherit the flags from the
@@ -623,10 +638,10 @@ public:
     long GetConvertVariantFlags() const;
 
     /**
-        Sets the flags used for conversions between wxVariant and OLE VARIANT,
+        Sets the flags used for conversions between wxVariant and OLE @c VARIANT,
-        see wxOleConvertVariantFlags.
+        see #wxOleConvertVariantFlags.
 
-        The default value is wxOleConvertVariant_Default.
+        The default value is ::wxOleConvertVariant_Default.
 
         @since 3.0
     */