Add documentation for wxSafeArray

This wxMSW-only class was introduced in 3.0 but was not documented.

Closes https://github.com/wxWidgets/wxWidgets/pull/1610

interface/wx/msw/ole/automtn.h

@@ -370,6 +370,185 @@ public:
     virtual bool GetAsAny(wxAny* any) const;
 };
 
+/**
+    @class wxSafeArray<varType>
+
+    wxSafeArray<varType> is wxWidgets wrapper for working with MS Windows @c
+    SAFEARRAY used in Component Object Model (COM) and OLE Automation APIs.
+
+    It also has convenience functions for converting between @c SAFEARRAY and
+    wxVariant with list type or wxArrayString.
+
+    wxSafeArray is a template class which must be created with an appropriate
+    type matching the underlying @c VARIANT type (such as @c VT_VARIANT or @c
+    VT_BSTR).
+
+    See wxVariantDataSafeArray documentation for examples of using it.
+
+    @onlyfor{wxmsw}
+    @since 3.0
+
+    @library{wxcore}
+    @category{data}
+
+    @see wxAutomationObject, wxVariantDataSafeArray, wxVariant
+
+    @header{wx/msw/ole/safearray.h}
+*/
+template <VARTYPE varType>
+class wxSafeArray<varType>
+{
+public:
+
+    /**
+        The default constructor.
+    */
+    wxSafeArray();
+
+    /**
+        The destructor unlocks and destroys the owned @c SAFEARRAY.
+    */
+    ~wxSafeArray();
+
+    /**
+        Creates and locks a zero-based one-dimensional @c SAFEARRAY with the
+        given number of elements.
+    */
+    bool Create(size_t count);
+
+    /**
+        Creates and locks a @c SAFEARRAY.
+
+        See @c SafeArrayCreate() in MSDN documentation for more information.
+    */
+    bool Create(SAFEARRAYBOUND* bound, size_t dimensions);
+
+    /**
+        Creates a zero-based one-dimensional @c SAFEARRAY from wxVariant
+        with the list type.
+
+        Can be called only for wxSafeArray<@c VT_VARIANT>.
+    */
+    bool CreateFromListVariant(const wxVariant& variant);
+
+    /**
+        Creates a zero-based one-dimensional @c SAFEARRAY from wxArrayString.
+
+        Can be called only for wxSafeArray<@c VT_BSTR>.
+    */
+    bool CreateFromArrayString(const wxArrayString& strings);
+
+    /**
+        Attaches and locks an existing @c SAFEARRAY.
+
+        The array must have the same @c VARTYPE as this wxSafeArray was
+        instantiated with.
+    */
+    bool Attach(SAFEARRAY* array);
+
+    /**
+        Unlocks the owned @c SAFEARRAY, returns it and gives up its ownership.
+    */
+    SAFEARRAY* Detach();
+
+    /**
+        Unlocks and destroys the owned @c SAFEARRAY.
+    */
+    void Destroy();
+
+    /**
+        Returns @true if it has a valid @c SAFEARRAY.
+    */
+    bool HasArray() const { return m_array != NULL; }
+
+    /**
+        Returns the number of dimensions.
+    */
+    size_t GetDim() const;
+
+    /**
+        Returns lower bound for dimension @a dim in @a bound.
+
+        Dimensions start at @c 1.
+    */
+    bool GetLBound(size_t dim, long& bound) const;
+
+    /**
+        Returns upper bound for dimension @a dim in @a bound.
+
+        Dimensions start at @c 1.
+    */
+    bool GetUBound(size_t dim, long& bound) const;
+
+    /**
+        Returns element count for dimension @a dim. Dimensions start at @c 1.
+    */
+    size_t GetCount(size_t dim) const;
+
+    /**
+        Change the value of the specified element.
+
+        @a indices have the same row-column order as @c rgIndices i
+        @c SafeArrayPutElement(), i.e., the right-most dimension is
+        <tt>rgIndices[0]</tt> and the left-most dimension is stored at
+        <tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
+
+        @a element must be of type matching @c varType this wxSafeArray was
+        created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
+        wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
+        wxSafeArray<@c VT_R8>.
+    */
+    bool SetElement(long* indices, const externT& element);
+
+    /**
+        Retrieve the value of the specified element.
+
+        @a indices have the same row-column order as @c rgIndices in
+        @c SafeArrayGetElement(), i.e., the right-most dimension is
+        <tt>rgIndices[0]</tt> and the left-most dimension is stored at
+        <tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
+
+        @a element must be of type matching @c varType this wxSafeArray was
+        created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
+        wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
+        wxSafeArray<@c VT_R8>.
+    */
+    bool GetElement(long* indices, externT& element) const;
+
+    /**
+        Converts the array to a wxVariant with the list type, regardless of the
+        underlying @c SAFEARRAY type.
+
+        If the array is multidimensional, it is flattened using the algorithm
+        originally employed in wxConvertOleToVariant().
+    */
+    bool ConvertToVariant(wxVariant& variant) const;
+
+    /**
+        Converts an array to wxArrayString.
+
+        Can be called only for wxSafeArray<@c VT_BSTR>. If the array is
+        multidimensional, it is flattened using the algorithm originally
+        employed in wxConvertOleToVariant().
+    */
+    bool ConvertToArrayString(wxArrayString& strings) const;
+
+    /**
+        Converts @a psa to wxVariant.
+
+        @see wxSafeArray<varType>::ConvertToVariant(wxVariant&) const
+    */
+    static bool ConvertToVariant(SAFEARRAY* psa, wxVariant& variant);
+
+    /**
+        Converts @a psa to wxArrayString.
+
+        @see wxSafeArray<varType>::ConvertToArrayString(wxArrayString&) const
+
+    */
+    static bool ConvertToArrayString(SAFEARRAY* psa, wxArrayString& strings);
+};
+
 /**
     @class wxAutomationObject