don't use wxScopedPtr<> in wxDocTemplate::CreateDocument() as the document is implicitly deleted by InitDocument() if its initialization fails; try to explain the (complex and inconsistent) rules for deleting the document in the manual

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

interface/wx/docview.h

@@ -85,9 +85,15 @@ public:
     virtual wxDocument* CreateDocument(const wxString& path, long flags = 0);
 
     /**
-        Creates a new instance of the associated view class. If you have not
-        supplied a wxClassInfo parameter to the template constructor, you will
-        need to override this function to return an appropriate view instance.
+        Creates a new instance of the associated view class.
+
+        If you have not supplied a wxClassInfo parameter to the template
+        constructor, you will need to override this function to return an
+        appropriate view instance.
+
+        If the new view initialization fails, it must call
+        wxDocument::RemoveView() for consistency with the default behaviour of
+        this function.
     */
     virtual wxView* CreateView(wxDocument* doc, long flags = 0);
 
@@ -162,10 +168,25 @@ public:
     virtual wxString GetViewName() const;
 
     /**
-        Initialises the document, calling wxDocument::OnCreate(). This is
-        called from CreateDocument().
+        Initialises the document, calling wxDocument::OnCreate().
+
+        This is called from CreateDocument().
+
+        If you override this method, notice that you must @em delete the @a doc
+        if its initialization fails for consistency with the default behaviour.
+
+        @param doc
+            The document to initialize.
+        @param path
+            The associated file path.
+        @param flags
+            Flags passed to CreateDocument().
+        @return
+            @true if the initialization was successful or @false if it failed
+            in which case @a doc should be deleted by this function.
     */
-    virtual bool InitDocument(wxDocument* doc, const wxString& path,
+    virtual bool InitDocument(wxDocument* doc,
+                              const wxString& path,
                               long flags = 0);
 
     /**
@@ -1192,9 +1213,22 @@ public:
 
     /**
         Called just after the document object is created to give it a chance to
-        initialize itself. The default implementation uses the template
-        associated with the document to create an initial view. If this
-        function returns @false, the document is deleted.
+        initialize itself.
+
+        The default implementation uses the template associated with the
+        document to create an initial view.
+
+        For compatibility reasons, this method may either delete the document
+        itself if its initialization fails or not do it in which case it is
+        deleted by caller. It is recommended to delete the document explicitly
+        in this function if it can't be initialized.
+
+        @param path
+            The associated file path.
+        @param flags
+            Flags passed to CreateDocument().
+        @return
+            @true if the initialization was successful or @false if it failed.
     */
     virtual bool OnCreate(const wxString& path, long flags);
 

src/common/docview.cpp

@@ -775,9 +775,16 @@ wxDocTemplate::~wxDocTemplate()
 // Tries to dynamically construct an object of the right class.
 wxDocument *wxDocTemplate::CreateDocument(const wxString& path, long flags)
 {
-    wxScopedPtr<wxDocument> doc(DoCreateDocument());
+    // InitDocument() is supposed to delete the document object if its
+    // initialization fails so don't use wxScopedPtr<> here: this is fragile
+    // but unavoidable because the default implementation uses CreateView()
+    // which may -- or not -- create a wxView and if it does create it and its
+    // initialization fails then the view destructor will delete the document
+    // (via RemoveView()) and as we can't distinguish between the two cases we
+    // just have to assume that it always deletes it in case of failure
+    wxDocument * const doc = DoCreateDocument();
 
-    return doc && InitDocument(doc.get(), path, flags) ? doc.release() : NULL;
+    return doc && InitDocument(doc, path, flags) ? doc : NULL;
 }
 
 bool