MM: cleanup of comments and asserts

Also adds a README to explain some of the code flow of MM.

Change-Id: I363fdd73824a8d41f7073b6de2e9c24184005397

2 files changed, 90 insertions, 28 deletions

diff --git a/sw/source/uibase/dbui/README b/sw/source/uibase/dbui/README
new file mode 100644
index 000000000000..c89ecc1ded3d
--- /dev/null
+++ b/sw/source/uibase/dbui/README
@@ -0,0 +1,48 @@
+Mail merge (MM) has *four modes*. The modes 1-3 are directly exposed to the
+user via different GUIs. The modes are:
+
+1. FILE    = saves the result as documents
+2. PRINTER = directly printes resulting documents
+3. EMAIL   = sends results as inidividual emails
+4. SHELL   = returns an internal document shell for further programming
+
+There is one property, which changes the overall behaviour of these modes:
+*bCreateSingleFile*. This is the primary controller of the mail merge source
+code workflow, as it affects all modes!
+
+This also has timing contraints: for individual files the result can be
+defined in advance, while further processing of the single result can just
+be done after the merging. It mainly affects printing and the generation
+of huge (1000+ datasets) combined non-PRINT merge results. A valid
+combined document has to follow contraints, which are already met by
+individual documents, as these are just modified copies.
+
+LO currently has six working combinations of mode and *bCreateSingleFile*
+The others, ''EMAIL+true'' and ''SHELL+false'', are currently not
+implemented. But the list contains implementation proposals for both.
+
+* Mode: FILE
+** false: Saves each merged document as an individual file. The file name can
+   be selected from a database column!
+** true: Saves a combined file of concated documents. Each document starts
+   with a new / reset page style. Depending on the page style this inserts
+   hidden blank pages
+* Mode: PRINTER
+** false: Generates indivividual print jobs, which may be grouped on some
+   platforms for easier abortion (needs verification!). All print options
+   affect only the individual document! Printing starts after the first
+   document is generated.
+** true: Generates a single print job. All print options affect the combined
+   document! This especially effects the results of reverse and N-UP printing.
+   Printing can just start after all documents are generated.
+* Mode: EMAIL
+** false: Each document can either be used as the email body (html or txt) or
+   be attached to a general email text. The emails are extracted from a DB
+   column, which must be provided!
+** true: *not implemented*. Could send the combined document to a single
+   email address.
+* Mode: SHELL
+** false: *not implemented*. Instead of a single shell this could return a
+   sequence of shells for the individual documents.
+** true: Returns the shell of the generated document. This is mainly
+   interesting for programmers. The document is just generated internally.
diff --git a/sw/source/uibase/dbui/dbmgr.cxx b/sw/source/uibase/dbui/dbmgr.cxx
index 308fccf603c1..219abc20d0b6 100644
--- a/sw/source/uibase/dbui/dbmgr.cxx
+++ b/sw/source/uibase/dbui/dbmgr.cxx
@@ -415,7 +415,7 @@ static bool lcl_GetColumnCnt(SwDSParam* pParam, const OUString& rColumnName,
 // import data
 bool SwDBManager::MergeNew( const SwMergeDescriptor& rMergeDesc, vcl::Window* pParent )
 {
-    OSL_ENSURE(!bInMerge && !pImpl->pMergeData, "merge already activated!");
+    assert( !bInMerge && !pImpl->pMergeData && "merge already activated!" );
 
     SwDBData aData;
     aData.nCommandType = sdb::CommandType::TABLE;
@@ -936,6 +936,10 @@ static void lcl_PreparePrinterOptions(
     }
 }
 
+/**
+ * Please have a look at the README in the same directory, before you make
+ * larger changes in this function!
+ */
 bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                                  const SwMergeDescriptor& rMergeDescriptor,
                                  vcl::Window* pParent)
@@ -980,6 +984,8 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
     OUString                            sMailBodyMimeType;
     rtl_TextEncoding                    sMailEncoding = ::osl_getThreadTextEncoding();
 
+    // bNoError should be handled together with m_bCancel. while an error
+    // should always also set cancel, cancel doesn't indicate an / set error.
     bool bNoError = true;
 
     uno::Reference< beans::XPropertySet > xColumnProp;
@@ -1029,7 +1035,7 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
             uno::Reference<document::XDocumentPropertiesSupplier>
                 xDPS(pSourceDocSh->GetModel(), uno::UNO_QUERY);
             xSourceDocProps.set(xDPS->getDocumentProperties());
-            OSL_ENSURE(xSourceDocProps.is(), "DocumentProperties is null");
+            assert( xSourceDocProps.is() && "DocumentProperties is null" );
         }
 
         if( !bMT_SHELL && pSourceDocSh->IsModified() )
@@ -1081,6 +1087,7 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
 
             if( !IsMergeSilent() )
             {
+                // construct the process dialog
                 pSourceWindow = &pSourceShell->GetView().GetEditWin();
                 if( ! pParent )
                     pParent = pSourceWindow;
@@ -1151,7 +1158,7 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                 // #i72517#
                 const SwPageDesc* pSourcePageDesc = pSourceShell->FindPageDescByName( sStartingPageDesc );
                 const SwFrameFormat& rMaster = pSourcePageDesc->GetMaster();
-                bPageStylesWithHeaderFooter = rMaster.GetHeader().IsActive()  ||
+                bPageStylesWithHeaderFooter = rMaster.GetHeader().IsActive() ||
                                                 rMaster.GetFooter().IsActive();
 
                 sModifiedStartingPageDesc = sStartingPageDesc;
@@ -1182,10 +1189,11 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
 
             long nStartRow, nEndRow;
             bool bFreezedLayouts = false;
-            // collect temporary files
+            // to collect temporary email files
             ::std::vector< OUString> aFilesToRemove;
 
-            // The SfxObjectShell will be closed explicitly later but it is more safe to use SfxObjectShellLock here
+            // The SfxObjectShell will be closed explicitly later but
+            // it is more safe to use SfxObjectShellLock here
             SfxObjectShellLock xWorkDocSh;
             SwView*            pWorkView             = nullptr;
             SwDoc*             pWorkDoc              = nullptr;
@@ -1310,12 +1318,15 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                             pEvtSrc->LaunchMailMergeEvent( aEvt );
                         }
 
+                        // working copy is merged - prepare final steps depending on merge options
+
                         if (bCreateSingleFile)
                         {
-                            pWorkDoc->RemoveInvisibleContent();
+                            assert( pTargetShell && "no target shell available!" );
 
-                            OSL_ENSURE( pTargetShell, "no target shell available!" );
-                            // copy created file into the target document
+                            // prepare working copy and target to append
+
+                            pWorkDoc->RemoveInvisibleContent();
                             rWorkShell.ConvertFieldsToText();
                             rWorkShell.SetNumberingRestart();
                             if( bSynchronizedDoc )
@@ -1323,15 +1334,15 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                                 lcl_RemoveSectionLinks( rWorkShell );
                             }
 
-                            // insert the document into the target document
-
-                            //#i72517# put the styles to the target document
-                            //if the source uses headers or footers each new copy need to copy a new page styles
-                            SwPageDesc* pTargetPageDesc(nullptr);
-                            if(bPageStylesWithHeaderFooter)
+                            // #i72517# put the styles to the target document
+                            // if the source uses headers or footers each working document
+                            // needs inidividual page styles
+                            SwPageDesc* pTargetPageDesc = nullptr;
+                            if( bPageStylesWithHeaderFooter )
                             {
-                                //create a new pagestyle
-                                //copy the pagedesc from the current document to the new document and change the name of the to-be-applied style
+                                // create a new pagestyle
+                                // copy the pagedesc from the current document to the new
+                                // document and change the name of the to-be-applied style
                                 OUString sNewPageDescName = lcl_FindUniqueName(pTargetShell, sStartingPageDesc, nDocNo );
                                 pTargetPageDesc = pTargetDoc->MakePageDesc( sNewPageDescName );
                                 const SwPageDesc* pWorkPageDesc = rWorkShell.FindPageDescByName( sStartingPageDesc );
@@ -1346,16 +1357,19 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                             else
                                 pTargetPageDesc = pTargetShell->FindPageDescByName( sModifiedStartingPageDesc );
 
-                            // insert the document into the target document
                             if ( (nMaxDumpDocs < 0) || (nDocNo <= nMaxDumpDocs) )
                                 lcl_SaveDebugDoc( xWorkDocSh, "WorkDoc", nDocNo );
+
+                            // append the working document to the target document
                             if( targetDocPageCount % 2 == 1 )
                                 ++targetDocPageCount; // Docs always start on odd pages (so offset must be even).
                             SwNodeIndex appendedDocStart = pTargetDoc->AppendDoc(*rWorkShell.GetDoc(),
                                 nStartingPageNo, pTargetPageDesc, !bWorkDocInitialized, targetDocPageCount);
                             targetDocPageCount += rWorkShell.GetPageCnt();
+
                             if ( (nMaxDumpDocs < 0) || (nDocNo <= nMaxDumpDocs) )
                                 lcl_SaveDebugDoc( xTargetDocShell, "MergeDoc" );
+
                             if (bMT_SHELL)
                             {
                                 SwDocMergeInfo aMergeInfo;
@@ -1430,7 +1444,7 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                                             //read in the temporary file and use it as mail body
                                             SfxMedium aMedium( sFileURL, StreamMode::READ);
                                             SvStream* pInStream = aMedium.GetInStream();
-                                            OSL_ENSURE(pInStream, "no output file created?");
+                                            assert( pInStream && "no output file created?" );
                                             if(pInStream)
                                             {
                                                 pInStream->SetStreamCharSet( sMailEncoding );
@@ -1465,7 +1479,7 @@ bool SwDBManager::MergeMailFiles(SwWrtShell* pSourceShell,
                                     }
                                     xMailDispatcher->enqueueMailMessage( xMessage );
                                     if(!xMailDispatcher->isStarted())
-                                            xMailDispatcher->start();
+                                        xMailDispatcher->start();
                                     //schedule for removal
                                     aFilesToRemove.push_back(sFileURL);
                                 }
@@ -1886,7 +1900,7 @@ OUString SwDBManager::GetDBField(uno::Reference<beans::XPropertySet> xColumnProp
 {
     uno::Reference< sdb::XColumn > xColumn(xColumnProps, uno::UNO_QUERY);
     OUString sRet;
-    OSL_ENSURE(xColumn.is(), "SwDBManager::::ImportDBField: illegal arguments");
+    assert( xColumn.is() && "SwDBManager::::ImportDBField: illegal arguments" );
     if(!xColumn.is())
         return sRet;
 
@@ -2224,7 +2238,8 @@ bool SwDBManager::ExistsNextRecord() const
 sal_uInt32  SwDBManager::GetSelectedRecordId()
 {
     sal_uInt32  nRet = 0;
-    OSL_ENSURE(pImpl->pMergeData && pImpl->pMergeData->xResultSet.is(), "no data source in merge");
+    assert( pImpl->pMergeData &&
+            pImpl->pMergeData->xResultSet.is() && "no data source in merge" );
     if(!pImpl->pMergeData || !pImpl->pMergeData->xResultSet.is())
         return 0;
     try
@@ -2239,7 +2254,8 @@ sal_uInt32  SwDBManager::GetSelectedRecordId()
 
 bool SwDBManager::ToRecordId(sal_Int32 nSet)
 {
-    OSL_ENSURE(pImpl->pMergeData && pImpl->pMergeData->xResultSet.is(), "no data source in merge");
+    assert( pImpl->pMergeData &&
+            pImpl->pMergeData->xResultSet.is() && "no data source in merge" );
     if(!pImpl->pMergeData || !pImpl->pMergeData->xResultSet.is()|| nSet < 0)
         return false;
     bool bRet = false;
@@ -2827,14 +2843,14 @@ void SwDBManager::ExecuteFormLetter( SwWrtShell& rSh,
         pFound = FindDSConnection(sDataSource, true);
     }
     SwAbstractDialogFactory* pFact = SwAbstractDialogFactory::Create();
-    OSL_ENSURE(pFact, "Dialog creation failed!");
+    assert( pFact && "Factory creation failed!" );
     pImpl->pMergeDialog = pFact->CreateMailMergeDlg( DLG_MAILMERGE,
                                                         &rSh.GetView().GetViewFrame()->GetWindow(), rSh,
                                                         sDataSource,
                                                         sDataTableOrQuery,
                                                         nCmdType,
                                                         xConnection);
-    OSL_ENSURE(pImpl->pMergeDialog, "Dialog creation failed!");
+    assert( pImpl->pMergeDialog && "Dialog creation failed!" );
     if(pImpl->pMergeDialog->Execute() == RET_OK)
     {
         aDescriptor[svx::daSelection] <<= pImpl->pMergeDialog->GetSelection();
@@ -2855,7 +2871,6 @@ void SwDBManager::ExecuteFormLetter( SwWrtShell& rSh,
                         SwDocShell::Factory().GetFilterContainer() );
             try
             {
-
                 uno::Sequence< beans::PropertyValue > aValues(1);
                 beans::PropertyValue* pValues = aValues.getArray();
                 pValues[0].Name = "FilterName";
@@ -2994,13 +3009,12 @@ void SwDBManager::InsertText(SwWrtShell& rSh,
     aDBData.nCommandType = nCmdType;
 
     SwAbstractDialogFactory* pFact = SwAbstractDialogFactory::Create();
-    OSL_ENSURE(pFact, "SwAbstractDialogFactory fail!");
-
+    assert( pFact && "Factory creation failed!" );
     std::unique_ptr<AbstractSwInsertDBColAutoPilot> pDlg(pFact->CreateSwInsertDBColAutoPilot( rSh.GetView(),
                                                                                 xSource,
                                                                                 xColSupp,
                                                                                 aDBData ));
-    OSL_ENSURE(pDlg, "Dialog creation failed!");
+    assert( pDlg && "Dialog creation failed!" );
     if( RET_OK == pDlg->Execute() )
     {
         OUString sDummy;