sw: clarify what the hell SwTextFrame::GetFormatted() actually does

Change-Id: I3af0ef5f10c6c2172499b481f3fab1400dca3c6f

sw/source/core/inc/txtfrm.hxx

@@ -55,7 +55,12 @@ class SW_DLLPUBLIC SwTextFrame: public SwContentFrame
     friend class TextFrameLockGuard; // May Lock()/Unlock()
     friend bool sw_ChangeOffset( SwTextFrame* pFrame, sal_Int32 nNew );
 
-    static SwCache *pTextCache;  // Pointer to the Line Cache
+    /// SwLineLayout cache: the lines are not actually owned by the SwTextFrame
+    /// but by this SwCache, so they will be deleted in large documents
+    /// if there are too many of them, but the "valid" flags of the frame
+    /// will still be set; GetFormatted() is the function that forces
+    /// recreation of the SwLineLayout by Format() if necessary.
+    static SwCache *pTextCache;
     static long nMinPrtLine;    // This Line must not be underrun when printing
                                 // Hack for table cells stretching multiple pages
 
@@ -446,7 +451,7 @@ public:
     SwTextFrame *FindQuoVadisFrame();
 
     /**
-     * Makes up for formatting if the Idle Handler has struck
+     * In case the SwLineLayout was cleared out of the pTextCache, recreate it.
      *
      * #i29062# GetFormatted() can trigger a full formatting
      * of the paragraph, causing other layout frames to become invalid. This

sw/source/core/text/txtfrm.cxx

@@ -2123,18 +2123,18 @@ SwTextFrame* SwTextFrame::GetFormatted( bool bForceQuickFormat )
     vcl::RenderContext* pRenderContext = getRootFrame()->GetCurrShell()->GetOut();
     SwSwapIfSwapped swap( this );
 
-    // The IdleCollector could've removed my cached information
-    // Calc() calls our format
+    // In case the SwLineLayout was cleared out of the pTextCache, recreate it.
     // Not for empty paragraphs
     if( !HasPara() && !(isFrameAreaDefinitionValid() && IsEmpty()) )
     {
         // Calc() must be called, because frame position can be wrong
         const bool bFormat = isFrameAreaSizeValid();
-        Calc(pRenderContext);
+        Calc(pRenderContext); // calls Format() if invalid
 
-        // It could be that Calc() did not trigger Format(), because
-        // we've been asked by the IdleCollector to throw away our
-        // format information
+        // If the flags were valid (hence bFormat=true), Calc did nothing,
+        // so Format() must be called manually in order to recreate
+        // the SwLineLayout that has been deleted from the
+        // SwTextFrame::pTextCache (hence !HasPara() above).
         // Optimization with FormatQuick()
         if( bFormat && !FormatQuick( bForceQuickFormat ) )
             Format(getRootFrame()->GetCurrShell()->GetOut());