Reformat comments in core/layout up until LayoutBox

third_party/WebKit/Source/core/layout/ColumnBalancer.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "core/layout/LayoutMultiColumnSet.h"
 
 namespace blink {
 
-// A column balancer traverses a portion of the subtree of a flow thread that belongs to one or
-// more fragmentainer groups within one column set, in order to collect certain data to be used for
-// column balancing. This is an abstract class that just walks the subtree and leaves it to
-// subclasses to actually collect data.
+// A column balancer traverses a portion of the subtree of a flow thread that
+// belongs to one or more fragmentainer groups within one column set, in order
+// to collect certain data to be used for column balancing. This is an abstract
+// class that just walks the subtree and leaves it to subclasses to actually
+// collect data.
 class ColumnBalancer {
  protected:
   ColumnBalancer(const LayoutMultiColumnSet&,
                  LayoutUnit logicalTopInFlowThread,
                  LayoutUnit logicalBottomInFlowThread);
 
   const LayoutMultiColumnSet& columnSet() const { return m_columnSet; }
 
-  // The flow thread portion we're examining. It may be that of the entire column set, or just of
-  // a fragmentainer group.
+  // The flow thread portion we're examining. It may be that of the entire
+  // column set, or just of a fragmentainer group.
   const LayoutUnit logicalTopInFlowThread() const {
     return m_logicalTopInFlowThread;
   }
   const LayoutUnit logicalBottomInFlowThread() const {
     return m_logicalBottomInFlowThread;
   }
 
   const MultiColumnFragmentainerGroup& groupAtOffset(
       LayoutUnit offsetInFlowThread) const {
     return m_columnSet.fragmentainerGroupAtFlowThreadOffset(
         offsetInFlowThread, LayoutBox::AssociateWithLatterPage);
   }
 
   LayoutUnit offsetFromColumnLogicalTop(LayoutUnit offsetInFlowThread) const {
     return offsetInFlowThread -
            groupAtOffset(offsetInFlowThread)
                .columnLogicalTopForOffset(offsetInFlowThread);
   }
 
   // Flow thread offset for the layout object that we're currently examining.
   LayoutUnit flowThreadOffset() const { return m_flowThreadOffset; }
 
-  // Return true if the specified offset is at the top of a column, as long as it's not the first
-  // column in the flow thread portion.
+  // Return true if the specified offset is at the top of a column, as long as
+  // it's not the first column in the flow thread portion.
   bool isFirstAfterBreak(LayoutUnit flowThreadOffset) const {
     if (flowThreadOffset <= m_logicalTopInFlowThread) {
-      // The first column is either not after any break at all, or after a break in a
-      // previous fragmentainer group.
+      // The first column is either not after any break at all, or after a break
+      // in a previous fragmentainer group.
       return false;
     }
     return flowThreadOffset ==
            groupAtOffset(flowThreadOffset)
                .columnLogicalTopForOffset(flowThreadOffset);
   }
 
   bool isLogicalTopWithinBounds(LayoutUnit logicalTopInFlowThread) const {
     return logicalTopInFlowThread >= m_logicalTopInFlowThread &&
            logicalTopInFlowThread < m_logicalBottomInFlowThread;
   }
 
   bool isLogicalBottomWithinBounds(LayoutUnit logicalBottomInFlowThread) const {
     return logicalBottomInFlowThread > m_logicalTopInFlowThread &&
            logicalBottomInFlowThread <= m_logicalBottomInFlowThread;
   }
 
-  // Examine and collect column balancing data from a layout box that has been found to intersect
-  // with the flow thread portion we're examining. Does not recurse into
-  // children. flowThreadOffset() will return the offset from |box| to the flow thread. Two hooks
-  // are provided here. The first one is called right after entering and before traversing the
-  // subtree of the box, and the second one right after having traversed the subtree.
+  // Examine and collect column balancing data from a layout box that has been
+  // found to intersect with the flow thread portion we're examining. Does not
+  // recurse into children. flowThreadOffset() will return the offset from |box|
+  // to the flow thread. Two hooks are provided here. The first one is called
+  // right after entering and before traversing the subtree of the box, and the
+  // second one right after having traversed the subtree.
   virtual void examineBoxAfterEntering(const LayoutBox&,
                                        EBreak previousBreakAfterValue) = 0;
   virtual void examineBoxBeforeLeaving(const LayoutBox&) = 0;
 
-  // Examine and collect column balancing data from a line that has been found to intersect with
-  // the flow thread portion. Does not recurse into layout objects on that line.
+  // Examine and collect column balancing data from a line that has been found
+  // to intersect with the flow thread portion. Does not recurse into layout
+  // objects on that line.
   virtual void examineLine(const RootInlineBox&) = 0;
 
-  // Examine and collect column balancing data for everything in the flow thread portion. Will
-  // trigger calls to examineBoxAfterEntering(), examineBoxBeforeLeaving() and examineLine() for
-  // interesting boxes and lines.
+  // Examine and collect column balancing data for everything in the flow thread
+  // portion. Will trigger calls to examineBoxAfterEntering(),
+  // examineBoxBeforeLeaving() and examineLine() for interesting boxes and
+  // lines.
   void traverse();
 
  private:
   void traverseSubtree(const LayoutBox&);
 
   const LayoutMultiColumnSet& m_columnSet;
   const LayoutUnit m_logicalTopInFlowThread;
   const LayoutUnit m_logicalBottomInFlowThread;
 
   LayoutUnit m_flowThreadOffset;
 };
 
-// After an initial layout pass, we know the height of the contents of a flow thread. Based on
-// this, we can estimate an initial minimal column height. This class will collect the necessary
-// information from the layout objects to make this estimate. This estimate may be used to perform
-// another layout iteration. If we after such a layout iteration cannot fit the contents with the
-// given column height without creating overflowing columns, we will have to stretch the columns by
-// some amount and lay out again. We may need to do this several times (but typically not more
-// times than the number of columns that we have). The amount to stretch is provided by the sister
-// of this class, named MinimumSpaceShortageFinder.
+// After an initial layout pass, we know the height of the contents of a flow
+// thread. Based on this, we can estimate an initial minimal column height. This
+// class will collect the necessary information from the layout objects to make
+// this estimate. This estimate may be used to perform another layout iteration.
+// If we after such a layout iteration cannot fit the contents with the given
+// column height without creating overflowing columns, we will have to stretch
+// the columns by some amount and lay out again. We may need to do this several
+// times (but typically not more times than the number of columns that we have).
+// The amount to stretch is provided by the sister of this class, named
+// MinimumSpaceShortageFinder.
 class InitialColumnHeightFinder final : public ColumnBalancer {
  public:
   InitialColumnHeightFinder(const LayoutMultiColumnSet&,
                             LayoutUnit logicalTopInFlowThread,
                             LayoutUnit logicalBottomInFlowThread);
 
   LayoutUnit initialMinimalBalancedHeight() const;
 
-  // Height of the tallest piece of unbreakable content. This is the minimum column logical height
-  // required to avoid fragmentation where it shouldn't occur (inside unbreakable content, between
-  // orphans and widows, etc.). This will be used as a hint to the column balancer to help set a
-  // good initial column height.
+  // Height of the tallest piece of unbreakable content. This is the minimum
+  // column logical height required to avoid fragmentation where it shouldn't
+  // occur (inside unbreakable content, between orphans and widows, etc.). This
+  // will be used as a hint to the column balancer to help set a good initial
+  // column height.
   LayoutUnit tallestUnbreakableLogicalHeight() const {
     return m_tallestUnbreakableLogicalHeight;
   }
 
  private:
   void examineBoxAfterEntering(const LayoutBox&,
                                EBreak previousBreakAfterValue);
   void examineBoxBeforeLeaving(const LayoutBox&);
   void examineLine(const RootInlineBox&);
 
-  // Record that there's a pagination strut that ends at the specified |offsetInFlowThread|, which
-  // is an offset exactly at the top of some column.
+  // Record that there's a pagination strut that ends at the specified
+  // |offsetInFlowThread|, which is an offset exactly at the top of some column.
   void recordStrutBeforeOffset(LayoutUnit offsetInFlowThread, LayoutUnit strut);
 
-  // Return the accumulated space used by struts at all column boundaries preceding the specified
-  // flowthread offset.
+  // Return the accumulated space used by struts at all column boundaries
+  // preceding the specified flowthread offset.
   LayoutUnit spaceUsedByStrutsAt(LayoutUnit offsetInFlowThread) const;
 
-  // Add a content run, specified by its end position. A content run is appended at every
-  // forced/explicit break and at the end of the column set. The content runs are used to
-  // determine where implicit/soft breaks will occur, in order to calculate an initial column
-  // height.
+  // Add a content run, specified by its end position. A content run is appended
+  // at every forced/explicit break and at the end of the column set. The
+  // content runs are used to determine where implicit/soft breaks will occur,
+  // in order to calculate an initial column height.
   void addContentRun(LayoutUnit endOffsetInFlowThread);
 
-  // Return the index of the content run with the currently tallest columns, taking all implicit
-  // breaks assumed so far into account.
+  // Return the index of the content run with the currently tallest columns,
+  // taking all implicit breaks assumed so far into account.
   unsigned contentRunIndexWithTallestColumns() const;
 
-  // Given the current list of content runs, make assumptions about where we need to insert
-  // implicit breaks (if there's room for any at all; depending on the number of explicit breaks),
-  // and store the results. This is needed in order to balance the columns.
+  // Given the current list of content runs, make assumptions about where we
+  // need to insert implicit breaks (if there's room for any at all; depending
+  // on the number of explicit breaks), and store the results. This is needed in
+  // order to balance the columns.
   void distributeImplicitBreaks();
 
-  // A run of content without explicit (forced) breaks; i.e. a flow thread portion between two
-  // explicit breaks, between flow thread start and an explicit break, between an explicit break
-  // and flow thread end, or, in cases when there are no explicit breaks at all: between flow
-  // thread portion start and flow thread portion end. We need to know where the explicit breaks
-  // are, in order to figure out where the implicit breaks will end up, so that we get the columns
-  // properly balanced. A content run starts out as representing one single column, and will
-  // represent one additional column for each implicit break "inserted" there.
+  // A run of content without explicit (forced) breaks; i.e. a flow thread
+  // portion between two explicit breaks, between flow thread start and an
+  // explicit break, between an explicit break and flow thread end, or, in cases
+  // when there are no explicit breaks at all: between flow thread portion start
+  // and flow thread portion end. We need to know where the explicit breaks are,
+  // in order to figure out where the implicit breaks will end up, so that we
+  // get the columns properly balanced. A content run starts out as representing
+  // one single column, and will represent one additional column for each
+  // implicit break "inserted" there.
   class ContentRun {
    public:
     ContentRun(LayoutUnit breakOffset)
         : m_breakOffset(breakOffset), m_assumedImplicitBreaks(0) {}
 
     unsigned assumedImplicitBreaks() const { return m_assumedImplicitBreaks; }
     void assumeAnotherImplicitBreak() { m_assumedImplicitBreaks++; }
     LayoutUnit breakOffset() const { return m_breakOffset; }
 
-    // Return the column height that this content run would require, considering the implicit
-    // breaks assumed so far.
+    // Return the column height that this content run would require, considering
+    // the implicit breaks assumed so far.
     LayoutUnit columnLogicalHeight(LayoutUnit startOffset) const {
       return LayoutUnit::fromFloatCeil(float(m_breakOffset - startOffset) /
                                        float(m_assumedImplicitBreaks + 1));
     }
 
    private:
     LayoutUnit m_breakOffset;  // Flow thread offset where this run ends.
-    unsigned
-        m_assumedImplicitBreaks;  // Number of implicit breaks in this run assumed so far.
+    unsigned m_assumedImplicitBreaks;  // Number of implicit breaks in this run
+                                       // assumed so far.
   };
   Vector<ContentRun, 32> m_contentRuns;
 
-  // Shortest strut found at each column boundary (index 0 being the boundary between the first
-  // and the second column, index 1 being the one between the second and the third boundary, and
-  // so on). There may be several objects that cross the same column boundary, and we're only
-  // interested in the shortest one. For example, when having a float beside regular in-flow
-  // content, we end up with two parallel fragmentation flows [1]. The shortest strut found at a
-  // column boundary is the amount of space that we wasted at said column boundary, and it needs
-  // to be deducted when estimating the initial balanced column height, or we risk making the
-  // column row too tall. An entry set to LayoutUnit::max() means that we didn't detect any object
+  // Shortest strut found at each column boundary (index 0 being the boundary
+  // between the first and the second column, index 1 being the one between the
+  // second and the third boundary, and so on). There may be several objects
+  // that cross the same column boundary, and we're only interested in the
+  // shortest one. For example, when having a float beside regular in-flow
+  // content, we end up with two parallel fragmentation flows [1]. The shortest
+  // strut found at a column boundary is the amount of space that we wasted at
+  // said column boundary, and it needs to be deducted when estimating the
+  // initial balanced column height, or we risk making the column row too tall.
+  // An entry set to LayoutUnit::max() means that we didn't detect any object
   // crossing that boundary.
   //
   // [1] http://www.w3.org/TR/css3-break/#parallel-flows
   Vector<LayoutUnit, 32> m_shortestStruts;
 
   LayoutUnit m_tallestUnbreakableLogicalHeight;
 };
 
-// If we have previously used InitialColumnHeightFinder to estimate an initial column height, and
-// that didn't result in tall enough columns, we need subsequent layout passes where we increase
-// the column height by the minimum space shortage at column breaks. This class finds the minimum
-// space shortage after having laid out with the current column height.
+// If we have previously used InitialColumnHeightFinder to estimate an initial
+// column height, and that didn't result in tall enough columns, we need
+// subsequent layout passes where we increase the column height by the minimum
+// space shortage at column breaks. This class finds the minimum space shortage
+// after having laid out with the current column height.
 class MinimumSpaceShortageFinder final : public ColumnBalancer {
  public:
   MinimumSpaceShortageFinder(const LayoutMultiColumnSet&,
                              LayoutUnit logicalTopInFlowThread,
                              LayoutUnit logicalBottomInFlowThread);
 
   LayoutUnit minimumSpaceShortage() const { return m_minimumSpaceShortage; }
   unsigned forcedBreaksCount() const { return m_forcedBreaksCount; }
 
  private:
   void examineBoxAfterEntering(const LayoutBox&,
                                EBreak previousBreakAfterValue);
   void examineBoxBeforeLeaving(const LayoutBox&);
   void examineLine(const RootInlineBox&);
 
   void recordSpaceShortage(LayoutUnit shortage) {
-    // Only positive values are interesting (and allowed) here. Zero space shortage may
-    // be reported when we're at the top of a column and the element has zero
-    // height.
+    // Only positive values are interesting (and allowed) here. Zero space
+    // shortage may be reported when we're at the top of a column and the
+    // element has zero height.
     if (shortage > 0)
       m_minimumSpaceShortage = std::min(m_minimumSpaceShortage, shortage);
   }
 
   // The smallest amout of space shortage that caused a column break.
   LayoutUnit m_minimumSpaceShortage;
 
-  // Set when breaking before a block, and we're looking for the first unbreakable descendant, in
-  // order to report correct space shortage for that one.
+  // Set when breaking before a block, and we're looking for the first
+  // unbreakable descendant, in order to report correct space shortage for that
+  // one.
   LayoutUnit m_pendingStrut;
 
   unsigned m_forcedBreaksCount;
 };
 
 }  // namespace blink