sw: fix comments in SwRootFrame::CalcFrameRects()

Change-Id: I1af7fd09bb2d3636b97825724a988e7912a3653b
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/158428
Tested-by: Jenkins
Reviewed-by: Michael Stahl <michael.stahl@allotropia.de>

1 files changed, 26 insertions, 28 deletions

diff --git a/sw/source/core/layout/trvlfrm.cxx b/sw/source/core/layout/trvlfrm.cxx
index 0b4938f7fe8d..fab57c35c24b 100644
--- a/sw/source/core/layout/trvlfrm.cxx
+++ b/sw/source/core/layout/trvlfrm.cxx
@@ -175,8 +175,7 @@ bool SwLayoutFrame::GetModelPositionForViewPoint( SwPosition *pPos, Point &rPoin
     return bRet;
 }
 
-/** Searches the page containing the searched point. */
-
+/** Searches for the page containing the searched point. */
 bool SwPageFrame::GetModelPositionForViewPoint( SwPosition *pPos, Point &rPoint,
                              SwCursorMoveState* pCMS, bool bTestBackground ) const
 {
@@ -1993,28 +1992,29 @@ static void Add( SwRegionRects& rRegion, const SwRect& rRect )
 }
 
 /*
- * The following situations can happen:
- *  1. Start and end lie in one screen-row and in the same node
+ * The following situations can happen (simplified version, before
+ * CJK/CTL features were added):
+ *  1. Start and end in same line of text and in the same frame
  *     -> one rectangle out of start and end; and we're okay
- *  2. Start and end lie in one frame (therefore in the same node!)
+ *  2. Start and end in same frame
  *     -> expand start to the right, end to the left and if more than two
- *        screen-rows are involved - calculate the in-between
- *  3. Start and end lie in different frames
+ *        lines of text are involved - calculate the in-between area
+ *  3. Start and end in different frames
  *     -> expand start to the right until frame-end, calculate Rect
  *        expand end to the left until frame-start, calculate Rect
  *        and if more than two frames are involved add the PrtArea of all
  *        frames which lie in between
  *
- * Big reorganization because of the FlyFrame - those need to be locked out.
+ * Big reorganization because of FlyFrame - those need to be excluded.
  * Exceptions:  - The Fly in which the selection took place (if it took place
  *                 in a Fly)
- *              - The Flys which are underrun by the text
+ *              - The Flys which are below the text (in z-order)
  *              - The Flys which are anchored to somewhere inside the selection.
  * Functioning: First a SwRegion with a root gets initialized.
- *              Out of the region the inverted sections are cut out. The
+ *              Out of the region the selected areas are cut out. The
  *              section gets compressed and finally inverted and thereby the
- *              inverted rectangles are available.
- *              In the end the Flys are cut out of the section.
+ *              rectangles are available for highlighting.
+ *              In the end the Flys are cut out of the region.
  */
 void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
 {
@@ -2026,7 +2026,6 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
     if (pSh)
         bIgnoreVisArea = pSh->GetViewOptions()->IsPDFExport() || comphelper::LibreOfficeKit::isActive();
 
-    // #i12836# enhanced pdf
     SwRegionRects aRegion( !bIgnoreVisArea ?
                            pSh->VisArea() :
                            getFrameArea() );
@@ -2055,7 +2054,7 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
     //tdf#119224 start and end are expected to exist for the scope of this function
     SwFrameDeleteGuard aStartFrameGuard(pStartFrame), aEndFrameGuard(pEndFrame);
 
-    //Do not subtract the FlyFrames in which selected Frames lie.
+    // Do not subtract FlyFrames that contain selected Frames.
     SwSortedObjs aSortObjs;
     if ( pStartFrame->IsInFly() )
     {
@@ -2071,7 +2070,7 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
     }
 
     // if a selection which is not allowed exists, we correct what is not
-    // allowed (header/footer/table-headline) for two pages.
+    // allowed (header/footer/table-headline start/end on different pages).
     do {    // middle check loop
         const SwLayoutFrame* pSttLFrame = pStartFrame->GetUpper();
         const SwFrameType cHdFtTableHd = SwFrameType::Header | SwFrameType::Footer | SwFrameType::Tab;
@@ -2377,7 +2376,7 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
               MultiPortionType::ROT_270 == pSt2Pos->nMultiType ||
               MultiPortionType::ROT_90  == pSt2Pos->nMultiType ) &&
             pSt2Pos->aPortion == pEnd2Pos->aPortion;
-        //case 1: (Same frame and same row)
+        // case 1: (Same frame and same line)
         if( bSameRotatedOrBidi ||
             aRectFnSet.GetTop(aStRect) == aRectFnSet.GetTop(aEndRect) )
         {
@@ -2400,9 +2399,8 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
             }
 
             SwRect aTmp( aTmpSt, aTmpEnd );
-            // Bug 34888: If content is selected which doesn't take space
-            //            away (i.e. PostIts, RefMarks, TOXMarks), then at
-            //            least set the width of the Cursor.
+            // If content is selected which doesn't take space (e.g. PostIts,
+            // RefMarks, TOXMarks), then at least set the width of the Cursor.
             if( 1 == aRectFnSet.GetWidth(aTmp) &&
                 pStartPos->GetContentIndex() !=
                 pEndPos->GetContentIndex() )
@@ -2444,7 +2442,7 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
             Sub( aRegion, aSubRect );
 
             //If there's at least a twips between start- and endline,
-            //so the whole area between will be added.
+            //the whole area between will be added.
             SwTwips aTmpBottom = aRectFnSet.GetBottom(aStRect);
             SwTwips aTmpTop = aRectFnSet.GetTop(aEndRect);
             if( aTmpBottom != aTmpTop )
@@ -2542,7 +2540,7 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
         if ( aPrvRect.HasArea() )
             Sub( aRegion, aPrvRect );
 
-        //At least the endframe...
+        // At last the endframe...
         aRectFnSet.Refresh(pEndFrame);
         nTmpTwips = aRectFnSet.GetTop(aEndRect);
         if( aRectFnSet.GetTop(aEndFrame) != nTmpTwips )
@@ -2563,12 +2561,12 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
     pSt2Pos.reset();
     pEnd2Pos.reset();
 
-    // Cut out Flys during loop. We don't cut out Flys when:
-    // - the Lower is StartFrame/EndFrame (FlyInCnt and all other Flys which again
-    //   sit in it)
-    // - if in the Z-order we have Flys above those in which the StartFrame is
-    //   placed
-    // - if they are anchored to inside the selection and thus part of it
+    // Cut out Flys in the foreground. We don't cut out a Fly when:
+    // - it's a Lower of StartFrame/EndFrame (FLY_AS_CHAR and all other Flys
+    //   which sit in it recursively)
+    // - it's lower in the Z-order than the fly that contains the StartFrame
+    //   (i.e. the one with the StartFrame is painted on top of it)
+    // - it's anchored to inside the selection and thus part of it
     const SwPageFrame *pPage      = pStartFrame->FindPageFrame();
     const SwPageFrame *pEndPage   = pEndFrame->FindPageFrame();
 
@@ -2631,7 +2629,7 @@ void SwRootFrame::CalcFrameRects(SwShellCursor &rCursor)
             pPage = static_cast<const SwPageFrame*>(pPage->GetNext());
     }
 
-    //Because it looks better, we close the DropCaps.
+    // Because it looks better, we cut out the DropCaps.
     SwRect aDropRect;
     if ( pStartFrame->IsTextFrame() )
     {