Add a class comment to LayoutText

Source/core/layout/LayoutText.h

 /*
  * (C) 1999 Lars Knoll (knoll@kde.org)
  * (C) 2000 Dirk Mueller (mueller@kde.org)
  * Copyright (C) 2004-2009, 2013 Apple 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 19 matching lines @@
 #include "platform/LengthFunctions.h"
 #include "platform/text/TextPath.h"
 #include "wtf/Forward.h"
 #include "wtf/PassRefPtr.h"
 
 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 to break the text into actual lines.
+// The result of layout is the line box tree, which represents lines
+// 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
     // not the content of the Text node, updating text-transform property
     // doesn't re-transform the string.
     LayoutText(Node*, PassRefPtr<StringImpl>);
 #if ENABLE(ASSERT)
     ~LayoutText() override;
 #endif
 
@@ skipping 114 matching lines @@
     void computePreferredLogicalWidths(float leadWidth);
     void computePreferredLogicalWidths(float leadWidth, HashSet<const SimpleFontData*>& fallbackFonts, FloatRect& glyphBounds);
 
     bool computeCanUseSimpleFontCodePath() const;
 
     // Make length() private so that callers that have a LayoutText*
     // will use the more efficient textLength() instead, while
     // 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; }
 
     void deleteTextBoxes();
     bool containsOnlyWhitespace(unsigned from, unsigned len) const;
     float widthFromFont(const Font&, int start, int len, float leadWidth, float textWidthSoFar, TextDirection, HashSet<const SimpleFontData*>* fallbackFonts, FloatRect* glyphBoundsAccumulation) const;
 
     void secureText(UChar mask);
 
@@ skipping 19 matching lines @@
     bool m_canUseSimpleFontCodePath : 1;
     mutable bool m_knownToHaveNoOverflowAndNoFallbackFonts : 1;
 
     float m_minWidth;
     float m_maxWidth;
     float m_firstLineMinWidth;
     float m_lastLineLineMinWidth;
 
     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;
 };
 
 inline UChar LayoutText::uncheckedCharacterAt(unsigned i) const
 {
     ASSERT_WITH_SECURITY_IMPLICATION(i < textLength());
     return is8Bit() ? characters8()[i] : characters16()[i];
 }
 
@@ skipping 22 matching lines @@
 inline LayoutText* Text::layoutObject() const
 {
     return toLayoutText(CharacterData::layoutObject());
 }
 
 void applyTextTransform(const ComputedStyle*, String&, UChar);
 
 } // namespace blink
 
 #endif // LayoutText_h