Better document some of the code in RowPainter.

Added a check in table-cell_number-rows-spanned_bug38397.xml which is the reason for one of the if-branches in RowPainter. It wan't tested previously so that if-branch could easily be mistaken to be useless.

git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@521713 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/fop/layoutmgr/table/RowPainter.java

@@ -48,6 +48,11 @@ class RowPainter {
      * part present on the current page.
      */
     private int[] firstRow = new int[3];
+    /**
+     * Keeps track of the y-offsets of each row on a page (for body, header and footer separately).
+     * This is particularly needed for spanned cells where you need to know the y-offset
+     * of the starting row when the area is generated at the time the cell is closed.
+     */
     private Map[] rowOffsets = new Map[] {new java.util.HashMap(),
             new java.util.HashMap(), new java.util.HashMap()};
 
@@ -237,17 +242,26 @@ class RowPainter {
         tclm.addRowBackgroundArea(rowFO, actualRowHeight, layoutContext.getRefIPD(), yoffset);
         for (int i = 0; i < primaryGridUnits.length; i++) {
             GridUnit currentGU = lastRow.safelyGetGridUnit(i);
+            //currentGU can be null if there's no grid unit
+            //at this place in the current row (empty cell and no borders to process)
+            
             if ((primaryGridUnits[i] != null)
                     && (forcedFlush || (end[i] == primaryGridUnits[i].getElements().size() - 1)
-                            && (currentGU == null || currentGU.isLastGridUnitRowSpan()))
-                || (primaryGridUnits[i] == null && currentGU != null)) {
-                //the last line in the "if" above is to avoid a premature end of an
+                            && /*[1]*/ (currentGU == null || currentGU.isLastGridUnitRowSpan()))
+                || /*[2]*/ (primaryGridUnits[i] == null && currentGU != null)) {
+                
+                //[1] the last line in the "if" above is to avoid a premature end of a
                 //row-spanned cell because no GridUnitParts are generated after a cell is
-                //finished with its content. currentGU can be null if there's no grid unit
-                //at this place in the current row (empty cell and no borders to process)
+                //finished with its content.
+                //See table-cell_number-rows-spanned_bug38397.xml
+                
+                //[2] A row-spanned cell has finished contributing content on the previous page
+                //and now still has to cause grid units to be painted.
+                //See table-cell_page-break_span.xml
+                
                 if (log.isDebugEnabled()) {
-                    log.debug((forcedFlush ? "FORCED " : "") + "flushing..." + i + " "
-                            + start[i] + "-" + end[i]);
+                    log.debug((forcedFlush ? "FORCED " : "") + "flushing... col=" + i 
+                            + " elem-list:" + start[i] + "-" + end[i]);
                 }
                 PrimaryGridUnit gu = primaryGridUnits[i];
                 if (gu == null
@@ -282,6 +296,8 @@ class RowPainter {
         //Determine y offset for the cell
         Integer offset = (Integer)rowOffsets[bt].get(new Integer(startRow));
         while (offset == null) {
+            //TODO Figure out what this does and when it's triggered
+            //This block is probably never used, at least it's not triggered by any of our tests
             startRow--;
             offset = (Integer)rowOffsets[bt].get(new Integer(startRow));
         }

test/layoutengine/standard-testcases/table-cell_number-rows-spanned_bug38397.xml

@@ -39,7 +39,7 @@
             <fo:table-column column-width="proportional-column-width(2)"/>
             <fo:table-body>
               <fo:table-row>
-                <fo:table-cell number-rows-spanned="3" number-columns-spanned="2" display-align="center" border="solid 0.5pt">
+                <fo:table-cell id="cell1" number-rows-spanned="3" number-columns-spanned="2" display-align="center" border="solid 0.5pt">
                   <fo:block>cell1</fo:block>
                 </fo:table-cell>
                 <fo:table-cell number-rows-spanned="2" display-align="center" border="solid 0.5pt">
@@ -94,5 +94,6 @@
   </fo>
   <checks>
     <eval expected="1" xpath="count(//pageViewport)"/>
+    <eval expected="45200" xpath="//block[@prod-id = 'cell1']/@bpd"/>
   </checks>
 </testcase>