Update layout location documentation to reflect renames.

third_party/WebKit/Source/core/layout/README.md

 # `Source/core/layout`
 
 This directory contains implementation of layout objects. It covers the
 following document lifecycle states:
 
 * LayoutSubtreeChange (`InLayoutSubtreeChange` and `LayoutSubtreeChangeClean`)
 * PreLayout (`InPreLayout`)
 * PerformLayout (`InPerformLayout`)
 * AfterPerformLayout (`AfterPerformLayout` and `LayoutClean`)
 
@@ skipping 194 matching lines @@
 performant code, so care should be taken to understand and document any changes
 to flipping logic.
 
 Blink test coverage for features used in vertical writing modes, and
 `vertical-rl` in particular, may not be as comprehensive as for horizontal
 writing mode. Keep this in mind when writing new functionality or tests by
 making sure to incorporate coverage for all writing modes when appropriate.
 
 Values are generally transformed into flipped block-flow coordinates via a set
 of methods on the involved layout objects. See in particular
-`flipForWritingMode()`, `flipForWritingModeForChild()`, and `topLeftLocation()`.
+`flipForWritingMode()`, `flipForWritingModeForChild()`.
 
 `InlineBox::flipForWritingMode()` variants flip the input value within the
 inline box's containing block.
 
 `LayoutBox::flipForWritingMode()` variants flip the input value within the
 referenced box.
 
 `LayoutBox::flipForWritingModeForChild()` variants flip the input value within
 the referenced box, offsetting for the specified child box's current x-position
 and width. This is useful for a common pattern wherein we build up a point
 location starting with the current location of the (child) box.
 
-`LayoutBox::topLeftLocation()` performs flipping as needed. If the containing
-block is not passed to the method, looking it up requires walking up the layout
-tree, which can be expensive.
+For LayoutBox and LayoutInline classes and subclasses:

[Xianzhu, 2016/11/29 23:36:29]

s/LayoutInline/InlineBox/

[wkorman, 2016/12/01 18:53:48]

Done.

+
+`physicalLocation()` returns the physical location of a box or inline in the
+containing block. `(0,0)` is the top-left corner of the containing
+block. Flipping is performed on the values as needed. If the containing block is

[Xianzhu, 2016/11/29 23:36:29]

The last sentence should apply to LayoutBox only.

InlineBox::physicalLocation() is expensive only if the InlineBox is in flipped
block-flow writing mode.

[wkorman, 2016/12/01 18:53:48]

Done.

+not passed to the method, looking it up requires walking up the layout tree,
+which can be expensive.
+
+`location()` returns the location of a box or inline in the "physical
+coordinates with flipped block-flow direction" coordinate space. `(0,0)` is the
+top-left corner of the containing block for `writing-mode` in normal blocks
+direction (`horizontal-tb` and `vertical-lr`), and is the top-right corner of
+the containing block for `writing-mode` in flipped block-flow direction
+(`vertical-rl`).
 
 Note there are two primary similar, but slightly different, methods regarding
 finding the containing block for an element:
 
 * `LayoutObject::container()` returns the containing block for an element as
 defined by CSS.
 * `LayoutObject::containingBlock()` which returns the enclosing non-anonymous
 block for an element. If the containing block is a relatively positioned inline,
 it returns that inline's enclosing non-anonymous block. This is the one used by
 `topLeftLocation()`.

[Xianzhu, 2016/11/29 23:36:29]

=> physicalLocation()

[wkorman, 2016/12/01 18:53:48]

Done.

 
 There are other containing block methods in `LayoutObject` for special purposes
 such as fixed position, absolute position, and paint invalidation.  Code will
 sometimes just refer to the 'containing' element, which is an unfortunately
 ambiguous term.  Paying close attention to which method was used to obtain the
 containing element is important.
 
 More complex web platform features such as tables, flexbox, and multicol are
 typically implemented atop these primitives, along with checks such as
 `isFlippedBlocksWritingMode()`, `isLeftToRightDirection()`, and
@@ skipping 45 matching lines @@
   left-to-right or right-to-left block flow. Geometry is transposed for vertical
   writing mode. See calls to `transposed{Rect,Point,Size}()`.
 * `direction`/`dir`: "inline base direction" of a box. One of `ltr` or
   `rtl`. See calls to `isLeftToRightDirection()`.
 * `text-orientation`: orientation of text in a line. Only relevant for vertical
   modes.
 * orthogonal flow: when a box has a writing mode perpendicular to its containing
   block. This can lead to complex cases. See
   [specification](https://www.w3.org/TR/css-writing-modes-3/#orthogonal-flows)
   for more.