Update layout documentation re: coordinate systems and writing mode.

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

 /*
  * Copyright (C) 1999 Lars Knoll (knoll@kde.org)
  *           (C) 1999 Antti Koivisto (koivisto@kde.org)
  * Copyright (C) 2003, 2006, 2007, 2009 Apple Inc. All rights reserved.
  * Copyright (C) 2010 Google Inc. All rights reserved.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
  * License as published by the Free Software Foundation; either
  * version 2 of the License, or (at your option) any later version.
@@ skipping 68 matching lines @@
 //
 // An important member of this class is PaintLayer. This class is
 // central to painting and hit-testing (see its class comment).
 // PaintLayers are instantiated for several reasons based on the
 // return value of layerTypeRequired().
 // Interestingly, most SVG objects inherit from LayoutSVGModelObject and thus
 // can't have a PaintLayer. This is an unfortunate artifact of our
 // design as it limits code sharing and prevents hardware accelerating SVG
 // (the current design require a PaintLayer for compositing).
 //
-//
-// ***** COORDINATE SYSTEMS *****
-//
-// In order to fully understand LayoutBoxModelObject and the inherited classes,
-// we need to introduce the concept of coordinate systems.
-// There is 3 main coordinate systems:
-// - physical coordinates: it is the coordinate system used for painting and
-//   correspond to physical direction as seen on the physical display (screen,
-//   printed page). In CSS, 'top', 'right', 'bottom', 'left' are all in physical
-//   coordinates. The code matches this convention too.
-//
-// - logical coordinates: this is the coordinate system used for layout. It is
-//   determined by 'writing-mode' and 'direction'. Any property using 'before',
-//   'after', 'start' or 'end' is in logical coordinates. Those are also named
-//   respectively 'logical top', 'logical bottom', 'logical left' and
-//   'logical right'.
-//
-// Example with writing-mode: vertical-rl; direction: ltr;
-//
-//                    'top' / 'start' side
-//
-//                     block-flow direction
-//           <------------------------------------ |
-//           ------------------------------------- |
-//           |        c   |          s           | |
-// 'left'    |        o   |          o           | |   inline     'right'
-//    /      |        n   |          m           | |  direction      /
-// 'after'   |        t   |          e           | |              'before'
-//  side     |        e   |                      | |                side
-//           |        n   |                      | |
-//           |        t   |                      | |
-//           ------------------------------------- v
-//
-//                 'bottom' / 'end' side
-//
-// See https://drafts.csswg.org/css-writing-modes-3/#text-flow for some
-// extra details.
-//
-// - physical coordinates with flipped block-flow direction: those are physical
-//   coordinates but we flipped the block direction. See
-//   LayoutBox::noOverflowRect.
-//   TODO(jchaffraix): I don't fully understand why we need this coordinate
-//   system someone should fill in those details.
+// For more on the coordinate systems used by this class and its subclasses, see
+// Source/core/layout/README.md ### Coordinate Spaces.

[eae, 2016/09/29 23:06:08]

Thank you for updating the README file, please leave a summary of the coordinate
system description in here (as a comment) though as everyone who looks at this
code will immediately see that. The overhead of looking at a raw markdown file
or finding a tool to translate it into HTML is much too high for it to replace a
well throughout inline description.

[wkorman, 2016/09/29 23:24:30]

Done.

 class CORE_EXPORT LayoutBoxModelObject : public LayoutObject {
 public:
     LayoutBoxModelObject(ContainerNode*);
     ~LayoutBoxModelObject() override;
 
     // This is the only way layers should ever be destroyed.
     void destroyLayer();
 
     LayoutSize relativePositionOffset() const;
     LayoutSize relativePositionLogicalOffset() const { return style()->isHorizontalWritingMode() ? relativePositionOffset() : relativePositionOffset().transposedSize(); }
@@ skipping 238 matching lines @@
     std::unique_ptr<PaintLayer> m_layer;
 
     std::unique_ptr<LayoutBoxModelObjectRareData> m_rareData;
 };
 
 DEFINE_LAYOUT_OBJECT_TYPE_CASTS(LayoutBoxModelObject, isBoxModelObject());
 
 } // namespace blink
 
 #endif // LayoutBoxModelObject_h