Bug 1613732 Part 1 - Revise documentation for ReflowChildFlags, ReflowChild(), and FinishReflowChild(). r=dholbert

The entire comment deleted in nsContainerFrame.cpp belongs to
FinishReflowChild(), which is already documented in the header.

Change `aChildFrame` to `aKidFrame` for ReflowChild() to match its
implementation.

Differential Revision: https://phabricator.services.mozilla.com/D61885

--HG--
extra : moz-landing-system : lando

layout/generic/nsContainerFrame.cpp

@@ -993,24 +993,6 @@ void nsContainerFrame::PositionChildViews(nsIFrame* aFrame) {
   }
 }
 
-/**
- * The second half of frame reflow. Does the following:
- * - sets the frame's bounds
- * - sizes and positions (if requested) the frame's view. If the frame's final
- *   position differs from the current position and the frame itself does not
- *   have a view, then any child frames with views are positioned so they stay
- *   in sync
- * - sets the view's visibility, opacity, content transparency, and clip
- * - invoked the DidReflow() function
- *
- * Flags:
- * ReflowChildFlags::NoMoveFrame - don't move the frame. aX and aY are ignored
- *    in this case. Also implies ReflowChildFlags::NoMoveView
- * ReflowChildFlags::NoMoveView - don't position the frame's view. Set this if
- *    you don't want to automatically sync the frame and view
- * ReflowChildFlags::NoSizeView - don't size the frame's view
- */
-
 /**
  * De-optimize function to work around a VC2017 15.5+ compiler bug:
  * https://bugzil.la/1424281#c12

layout/generic/nsContainerFrame.h

@@ -159,11 +159,6 @@ class nsContainerFrame : public nsSplittableFrame {
                                     nsIFrame* aNewParentFrame);
 
   // Set the view's size and position after its frame has been reflowed.
-  //
-  // Flags:
-  // NoMoveView - don't position the frame's view. Set this if you
-  //    don't want to automatically sync the frame and view
-  // NoSizeView - don't size the view
   static void SyncFrameViewAfterReflow(
       nsPresContext* aPresContext, nsIFrame* aFrame, nsView* aView,
       const nsRect& aVisualOverflowArea,
@@ -210,19 +205,18 @@ class nsContainerFrame : public nsSplittableFrame {
       const mozilla::LogicalSize& aPadding, ComputeSizeFlags aFlags) override;
 
   /**
-   * Positions aChildFrame and its view (if requested), and then calls Reflow().
-   * If the reflow status after reflowing the child is FULLY_COMPLETE then any
+   * Positions aKidFrame and its view (if requested), and then calls Reflow().
+   * If the reflow status after reflowing the child is FullyComplete then any
    * next-in-flows are deleted using DeleteNextInFlowChild().
    *
-   * @param aContainerSize  size of the border-box of the containing frame
+   * @param aWM Containing frame's writing-mode.
+   * @param aPos Position of the aKidFrame to be moved.
+   * @param aContainerSize Size of the border-box of the containing frame.
    *
-   * Flags:
-   * NoMoveView - don't position the frame's view. Set this if you
-   *    don't want to automatically sync the frame and view
-   * NoMoveFrame - don't move the frame. aPos is ignored in this
-   *    case. Also implies NoMoveView
+   * Note: If ReflowChildFlags::NoMoveFrame is requested, both aPos and
+   * aContainerSize are ignored.
    */
-  void ReflowChild(nsIFrame* aChildFrame, nsPresContext* aPresContext,
+  void ReflowChild(nsIFrame* aKidFrame, nsPresContext* aPresContext,
                    ReflowOutput& aDesiredSize, const ReflowInput& aReflowInput,
                    const mozilla::WritingMode& aWM,
                    const mozilla::LogicalPoint& aPos,
@@ -240,14 +234,13 @@ class nsContainerFrame : public nsSplittableFrame {
    * - sets the view's visibility, opacity, content transparency, and clip
    * - invoked the DidReflow() function
    *
-   * @param aContainerSize  size of the border-box of the containing frame
+   * @param aWM Containing frame's writing-mode.
+   * @param aPos Position of the aKidFrame to be positioned.
+   * @param aContainerSize Size of the border-box of the containing frame.
    *
-   * Flags:
-   * NoMoveFrame - don't move the frame. aPos is ignored in this
-   *    case. Also implies NoMoveView
-   * NoMoveView - don't position the frame's view. Set this if you
-   *    don't want to automatically sync the frame and view
-   * NoSizeView - don't size the frame's view
+   * Note: If ReflowChildFlags::NoMoveFrame is requested, both aPos and
+   * aContainerSize are ignored unless
+   * ReflowChildFlags::ApplyRelativePositioning is requested.
    */
   static void FinishReflowChild(
       nsIFrame* aKidFrame, nsPresContext* aPresContext,

layout/generic/nsIFrame.h

@@ -2570,13 +2570,22 @@ class nsIFrame : public nsQueryFrame {
                       const ReflowInput& aReflowInput,
                       nsReflowStatus& aStatus) = 0;
 
-  // Option flags for ReflowChild() and FinishReflowChild()
-  // member functions
+  // Option flags for ReflowChild(), FinishReflowChild(), and
+  // SyncFrameViewAfterReflow().
   enum class ReflowChildFlags : uint32_t {
     Default = 0,
+
+    // Don't position the frame's view. Set this if you don't want to
+    // automatically sync the frame and view.
     NoMoveView = 1 << 0,
+
+    // Don't move the frame. Also implies NoMoveView.
     NoMoveFrame = (1 << 1) | NoMoveView,
+
+    // Don't size the frame's view.
     NoSizeView = 1 << 2,
+
+    // TODO: This flag is not used. Will be removed.
     NoVisibility = 1 << 3,
 
     // Only applies to ReflowChild; if true, don't delete the next-in-flow, even