Add a class comment to LayoutText

Source/core/layout/LayoutText.h

Index: Source/core/layout/LayoutText.h
diff --git a/Source/core/layout/LayoutText.h b/Source/core/layout/LayoutText.h
index 155e94f12ffc32e402f961032a4a0dea535c713b..d5428307527500b6d13b21b493e54ed861e98493 100644
--- a/Source/core/layout/LayoutText.h
+++ b/Source/core/layout/LayoutText.h
@@ -37,6 +37,36 @@ namespace blink {
 class AbstractInlineTextBox;
 class InlineTextBox;
 
+// LayoutText is the root class for anything that represents
+// a text node (see core/dom/Text.h).
+//
+// This is a common node in the tree so to the limit memory overhead,
+// this class inherits directly from LayoutObject.
+// Also this class is used by both CSS and SVG layouts so LayoutObject
+// was a natural choice.
+//
+// The actual layout of text is handled by the containing inline
+// (LayoutInline) or block (LayoutBlock). They will invoke the Unicode
+// Bidirectional Algorithm algorithm to break the text into actual lines.

[eae, 2015/08/28 00:32:33]

s/Algorithm algorithm/algorithm/

[Julien - ping for review, 2015/08/28 02:18:41]

Done.

+// The result of layout is the line box tree, which represents text lines

[eae, 2015/08/28 00:32:33]

s/text lines/lines - as lines can contain inline boxes (non-text) as well.

[Julien - ping for review, 2015/08/28 02:18:41]

Done.

+// on the screen. It is stored into m_firstTextBox and m_lastTextBox.
+// To understand how lines are broken by the bidi algorithm, read e.g.
+// LayoutBlockFlow::layoutInlineChildren.
+//
+//
+// ***** LINE BOXES OWNERSHIP *****
+// m_firstTextBox and m_lastTextBox are not owned by LayoutText
+// but are pointers into the enclosing inline / block (see LayoutInline's
+// and LayoutBlock's m_lineBoxes).
+//
+//
+// This class implements the preferred logical widths computation
+// for its underlying text. The widths are stored into m_minWidth
+// and m_maxWidth. They are computed lazily based on
+// m_preferredLogicalWidthsDirty.
+//
+// The previous comment applies also for painting. See e.g.
+// BlockPainter::paintContents in particular the use of LineBoxListPainter.
 class CORE_EXPORT LayoutText : public LayoutObject {
 public:
     // FIXME: If the node argument is not a Text node or the string argument is
@@ -171,6 +201,7 @@ private:
     // callers with a LayoutObject* can continue to use length().
     unsigned length() const final { return textLength(); }
 
+    // See the class comment as to why we shouldn't call this function directly.
     void paint(const PaintInfo&, const LayoutPoint&) final { ASSERT_NOT_REACHED(); }
     void layout() final { ASSERT_NOT_REACHED(); }
     bool nodeAtPoint(HitTestResult&, const HitTestLocation&, const LayoutPoint&, HitTestAction) final { ASSERT_NOT_REACHED(); return false; }
@@ -210,6 +241,8 @@ private:
 
     String m_text;
 
+    // The line boxes associated with this object.
+    // Read the LINE BOXES OWNERSHIP section in the class header comment.
     InlineTextBox* m_firstTextBox;
     InlineTextBox* m_lastTextBox;
 };