Reflow comments in core/dom/.

third_party/WebKit/Source/core/dom/Node.h

 /*
  * Copyright (C) 1999 Lars Knoll (knoll@kde.org)
  *           (C) 1999 Antti Koivisto (koivisto@kde.org)
  *           (C) 2001 Dirk Mueller (mueller@kde.org)
  * Copyright (C) 2004-2011, 2014 Apple Inc. All rights reserved.
- * Copyright (C) 2008, 2009 Torch Mobile Inc. All rights reserved. (http://www.torchmobile.com/)
+ * Copyright (C) 2008, 2009 Torch Mobile Inc. All rights reserved.
+ * (http://www.torchmobile.com/)
  *
  * 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.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Library General Public License for more details.
@@ skipping 126 matching lines @@
     kAttributeNode = 2,
     kTextNode = 3,
     kCdataSectionNode = 4,
     kProcessingInstructionNode = 7,
     kCommentNode = 8,
     kDocumentNode = 9,
     kDocumentTypeNode = 10,
     kDocumentFragmentNode = 11,
   };
 
-  // Entity, EntityReference, and Notation nodes are impossible to create in Blink.
-  // But for compatibility reasons we want these enum values exist in JS, and this enum makes the bindings
-  // generation not complain about kEntityReferenceNode being missing from the implementation
-  // while not requiring all switch(NodeType) blocks to include this deprecated constant.
+  // Entity, EntityReference, and Notation nodes are impossible to create in
+  // Blink.  But for compatibility reasons we want these enum values exist in
+  // JS, and this enum makes the bindings generation not complain about
+  // kEntityReferenceNode being missing from the implementation while not
+  // requiring all switch(NodeType) blocks to include this deprecated constant.
   enum DeprecatedNodeType {
     kEntityReferenceNode = 5,
     kEntityNode = 6,
     kNotationNode = 12,
   };
 
   enum DocumentPosition {
     kDocumentPositionEquivalent = 0x00,
     kDocumentPositionDisconnected = 0x01,
     kDocumentPositionPreceding = 0x02,
@@ skipping 34 matching lines @@
   ContainerNode* parentElementOrShadowRoot() const;
   ContainerNode* parentElementOrDocumentFragment() const;
   Node* previousSibling() const { return m_previous; }
   Node* nextSibling() const { return m_next; }
   NodeList* childNodes();
   Node* firstChild() const;
   Node* lastChild() const;
   Node* getRootNode(const GetRootNodeOptions&) const;
   Node& treeRoot() const;
   Node& shadowIncludingRoot() const;
-  // closed-shadow-hidden is defined at https://dom.spec.whatwg.org/#concept-closed-shadow-hidden
+  // closed-shadow-hidden is defined at
+  // https://dom.spec.whatwg.org/#concept-closed-shadow-hidden
   bool isClosedShadowHiddenFrom(const Node&) const;
 
   void prepend(const HeapVector<NodeOrString>&, ExceptionState&);
   void append(const HeapVector<NodeOrString>&, ExceptionState&);
   void before(const HeapVector<NodeOrString>&, ExceptionState&);
   void after(const HeapVector<NodeOrString>&, ExceptionState&);
   void replaceWith(const HeapVector<NodeOrString>&, ExceptionState&);
   void remove(ExceptionState& = ASSERT_NO_EXCEPTION);
 
   Node* pseudoAwareNextSibling() const;
@@ skipping 89 matching lines @@
   // A re-distribution across v0 and v1 shadow trees is not supported.
   bool isSlotable() const {
     return isTextNode() || (isElementNode() && !isInsertionPoint());
   }
   AtomicString slotName() const;
 
   bool hasCustomStyleCallbacks() const {
     return getFlag(HasCustomStyleCallbacksFlag);
   }
 
-  // If this node is in a shadow tree, returns its shadow host. Otherwise, returns nullptr.
-  // TODO(kochi): crbug.com/507413 ownerShadowHost() can return nullptr even when it is in a
-  // shadow tree but its root is detached from its host. This can happen when handling
-  // queued events (e.g. during execCommand()).
+  // If this node is in a shadow tree, returns its shadow host. Otherwise,
+  // returns nullptr.
+  // TODO(kochi): crbug.com/507413 ownerShadowHost() can return nullptr even
+  // when it is in a shadow tree but its root is detached from its host. This
+  // can happen when handling queued events (e.g. during execCommand()).
   Element* ownerShadowHost() const;
-  // crbug.com/569532: containingShadowRoot() can return nullptr even if isInShadowTree() returns true.
+  // crbug.com/569532: containingShadowRoot() can return nullptr even if
+  // isInShadowTree() returns true.
   // This can happen when handling queued events (e.g. during execCommand())
   ShadowRoot* containingShadowRoot() const;
   ShadowRoot* youngestShadowRoot() const;
 
   // Returns nullptr, a child of ShadowRoot, or a legacy shadow root.
   Node* nonBoundaryShadowTreeRootNode();
 
   // Node's parent, shadow tree host.
   ContainerNode* parentOrShadowHostNode() const;
   Element* parentOrShadowHostElement() const;
   void setParentOrShadowHostNode(ContainerNode*);
 
   // Knows about all kinds of hosts.
   ContainerNode* parentOrShadowHostOrTemplateHostNode() const;
 
   // Returns the parent node, but nullptr if the parent node is a ShadowRoot.
   ContainerNode* nonShadowBoundaryParentNode() const;
 
-  // Returns the enclosing event parent Element (or self) that, when clicked, would trigger a navigation.
+  // Returns the enclosing event parent Element (or self) that, when clicked,
+  // would trigger a navigation.
   Element* enclosingLinkEventParentOrSelf() const;
 
-  // These low-level calls give the caller responsibility for maintaining the integrity of the tree.
+  // These low-level calls give the caller responsibility for maintaining the
+  // integrity of the tree.
   void setPreviousSibling(Node* previous) { m_previous = previous; }
   void setNextSibling(Node* next) { m_next = next; }
 
   virtual bool canContainRangeEndPoint() const { return false; }
 
   // For <link> and <style> elements.
   virtual bool sheetLoaded() { return true; }
   enum LoadedSheetErrorStatus {
     NoErrorLoadingSubresource,
     ErrorOccurredLoadingSubresource
   };
   virtual void notifyLoadedSheetAndAllCriticalSubresources(
       LoadedSheetErrorStatus) {}
   virtual void startLoadingDynamicSheet() { ASSERT_NOT_REACHED(); }
 
   bool hasName() const {
     DCHECK(!isTextNode());
     return getFlag(HasNameOrIsEditingTextFlag);
   }
 
   bool isUserActionElement() const { return getFlag(IsUserActionElementFlag); }
   void setUserActionElement(bool flag) {
     setFlag(flag, IsUserActionElementFlag);
   }
 
-  // TODO(yosin): We should rename |active()| to |isActive()| as |UserActionElementSet|.
+  // TODO(yosin): We should rename |active()| to |isActive()| as
+  // |UserActionElementSet|.
   bool active() const {
     return isUserActionElement() && isUserActionElementActive();
   }
   bool inActiveChain() const {
     return isUserActionElement() && isUserActionElementInActiveChain();
   }
   bool isDragged() const {
     return isUserActionElement() && isUserActionElementDragged();
   }
-  // TODO(yosin): We should rename |hovered()| to |isHovered()| as |UserActionElementSet|.
+  // TODO(yosin): We should rename |hovered()| to |isHovered()| as
+  // |UserActionElementSet|.
   bool hovered() const {
     return isUserActionElement() && isUserActionElementHovered();
   }
-  // Note: As a shadow host whose root with delegatesFocus=false may become focused state when
-  // an inner element gets focused, in that case more than one elements in a document can return
-  // true for |focused()|.  Use Element::isFocusedElementInDocument() or Document::focusedElement()
-  // to check which element is exactly focused.
+  // Note: As a shadow host whose root with delegatesFocus=false may become
+  // focused state when an inner element gets focused, in that case more than
+  // one elements in a document can return true for |focused()|.  Use
+  // Element::isFocusedElementInDocument() or Document::focusedElement() to
+  // check which element is exactly focused.
   bool focused() const {
     return isUserActionElement() && isUserActionElementFocused();
   }
 
   bool needsAttach() const {
     return getStyleChangeType() == NeedsReattachStyleChange;
   }
   bool needsStyleRecalc() const {
     return getStyleChangeType() != NoStyleChange;
   }
@@ skipping 92 matching lines @@
   // must be recognized as inert to prevent text selection.
   bool isInert() const;
 
   virtual LayoutRect boundingBox() const;
   IntRect pixelSnappedBoundingBox() const {
     return pixelSnappedIntRect(boundingBox());
   }
 
   unsigned nodeIndex() const;
 
-  // Returns the DOM ownerDocument attribute. This method never returns null, except in the case
-  // of a Document node.
+  // Returns the DOM ownerDocument attribute. This method never returns null,
+  // except in the case of a Document node.
   Document* ownerDocument() const;
 
-  // Returns the document associated with this node. A Document node returns itself.
+  // Returns the document associated with this node. A Document node returns
+  // itself.
   Document& document() const { return treeScope().document(); }
 
   TreeScope& treeScope() const {
     DCHECK(m_treeScope);
     return *m_treeScope;
   }
 
   TreeScope& containingTreeScope() const {
     DCHECK(isInTreeScope());
     return *m_treeScope;
@@ skipping 23 matching lines @@
   virtual bool childTypeAllowed(NodeType) const { return false; }
   unsigned countChildren() const;
 
   bool isDescendantOf(const Node*) const;
   bool contains(const Node*) const;
   bool isShadowIncludingInclusiveAncestorOf(const Node*) const;
   bool containsIncludingHostElements(const Node&) const;
   Node* commonAncestor(const Node&,
                        ContainerNode* (*parent)(const Node&)) const;
 
-  // Number of DOM 16-bit units contained in node. Note that laid out text length can be different - e.g. because of
-  // css-transform:capitalize breaking up precomposed characters and ligatures.
+  // Number of DOM 16-bit units contained in node. Note that laid out text
+  // length can be different - e.g. because of css-transform:capitalize breaking
+  // up precomposed characters and ligatures.
   virtual int maxCharacterOffset() const;
 
   // Whether or not a selection can be started in this object
   virtual bool canStartSelection() const;
 
   // -----------------------------------------------------------------------------
   // Integration with layout tree
 
-  // As layoutObject() includes a branch you should avoid calling it repeatedly in hot code paths.
-  // Note that if a Node has a layoutObject, it's parentNode is guaranteed to have one as well.
+  // As layoutObject() includes a branch you should avoid calling it repeatedly
+  // in hot code paths.
+  // Note that if a Node has a layoutObject, it's parentNode is guaranteed to
+  // have one as well.
   LayoutObject* layoutObject() const {
     return hasRareData() ? m_data.m_rareData->layoutObject()
                          : m_data.m_layoutObject;
   }
   void setLayoutObject(LayoutObject* layoutObject) {
     if (hasRareData())
       m_data.m_rareData->setLayoutObject(layoutObject);
     else
       m_data.m_layoutObject = layoutObject;
   }
 
   // Use these two methods with caution.
   LayoutBox* layoutBox() const;
   LayoutBoxModelObject* layoutBoxModelObject() const;
 
   struct AttachContext {
     STACK_ALLOCATED();
     ComputedStyle* resolvedStyle = nullptr;
     bool performingReattach = false;
     bool clearInvalidation = false;
 
     AttachContext() {}
   };
 
-  // Attaches this node to the layout tree. This calculates the style to be applied to the node and creates an
-  // appropriate LayoutObject which will be inserted into the tree (except when the style has display: none). This
+  // Attaches this node to the layout tree. This calculates the style to be
+  // applied to the node and creates an appropriate LayoutObject which will be
+  // inserted into the tree (except when the style has display: none). This
   // makes the node visible in the FrameView.
   virtual void attachLayoutTree(const AttachContext& = AttachContext());
 
-  // Detaches the node from the layout tree, making it invisible in the rendered view. This method will remove
-  // the node's layout object from the layout tree and delete it.
+  // Detaches the node from the layout tree, making it invisible in the rendered
+  // view. This method will remove the node's layout object from the layout tree
+  // and delete it.
   virtual void detachLayoutTree(const AttachContext& = AttachContext());
 
   void reattachLayoutTree(const AttachContext& = AttachContext());
   void lazyReattachIfAttached();
 
-  // Returns true if recalcStyle should be called on the object, if there is such a method (on Document and Element).
+  // Returns true if recalcStyle should be called on the object, if there is
+  // such a method (on Document and Element).
   bool shouldCallRecalcStyle(StyleRecalcChange);
 
-  // Wrapper for nodes that don't have a layoutObject, but still cache the style (like HTMLOptionElement).
+  // Wrapper for nodes that don't have a layoutObject, but still cache the style
+  // (like HTMLOptionElement).
   ComputedStyle* mutableComputedStyle() const;
   const ComputedStyle* computedStyle() const;
   const ComputedStyle* parentComputedStyle() const;
 
   const ComputedStyle& computedStyleRef() const;
 
   const ComputedStyle* ensureComputedStyle(
       PseudoId pseudoElementSpecifier = PseudoIdNone) {
     return virtualEnsureComputedStyle(pseudoElementSpecifier);
   }
 
   // -----------------------------------------------------------------------------
-  // Notification of document structure changes (see ContainerNode.h for more notification methods)
+  // Notification of document structure changes (see ContainerNode.h for more
+  // notification methods)
   //
-  // At first, WebKit notifies the node that it has been inserted into the document. This is called during document parsing, and also
-  // when a node is added through the DOM methods insertBefore(), appendChild() or replaceChild(). The call happens _after_ the node has been added to the tree.
-  // This is similar to the DOMNodeInsertedIntoDocument DOM event, but does not require the overhead of event
-  // dispatching.
+  // At first, Blinkt notifies the node that it has been inserted into the
+  // document. This is called during document parsing, and also when a node is
+  // added through the DOM methods insertBefore(), appendChild() or
+  // replaceChild(). The call happens _after_ the node has been added to the
+  // tree.  This is similar to the DOMNodeInsertedIntoDocument DOM event, but
+  // does not require the overhead of event dispatching.
   //
-  // WebKit notifies this callback regardless if the subtree of the node is a document tree or a floating subtree.
-  // Implementation can determine the type of subtree by seeing insertionPoint->isConnected().
-  // For a performance reason, notifications are delivered only to ContainerNode subclasses if the insertionPoint is out of document.
+  // Blink notifies this callback regardless if the subtree of the node is a
+  // document tree or a floating subtree.  Implementation can determine the type
+  // of subtree by seeing insertionPoint->isConnected().  For a performance
+  // reason, notifications are delivered only to ContainerNode subclasses if the
+  // insertionPoint is out of document.
   //
-  // There are another callback named didNotifySubtreeInsertionsToDocument(), which is called after all the descendant is notified,
-  // if this node was inserted into the document tree. Only a few subclasses actually need this. To utilize this, the node should
-  // return InsertionShouldCallDidNotifySubtreeInsertions from insertedInto().
+  // There are another callback named didNotifySubtreeInsertionsToDocument(),
+  // which is called after all the descendant is notified, if this node was
+  // inserted into the document tree. Only a few subclasses actually need
+  // this. To utilize this, the node should return
+  // InsertionShouldCallDidNotifySubtreeInsertions from insertedInto().
   //
   enum InsertionNotificationRequest {
     InsertionDone,
     InsertionShouldCallDidNotifySubtreeInsertions
   };
 
   virtual InsertionNotificationRequest insertedInto(
       ContainerNode* insertionPoint);
   virtual void didNotifySubtreeInsertionsToDocument() {}
 
   // Notifies the node that it is no longer part of the tree.
   //
-  // This is a dual of insertedInto(), and is similar to the DOMNodeRemovedFromDocument DOM event, but does not require the overhead of event
-  // dispatching, and is called _after_ the node is removed from the tree.
+  // This is a dual of insertedInto(), and is similar to the
+  // DOMNodeRemovedFromDocument DOM event, but does not require the overhead of
+  // event dispatching, and is called _after_ the node is removed from the tree.
   //
   virtual void removedFrom(ContainerNode* insertionPoint);
 
   // FIXME(dominicc): This method is not debug-only--it is used by
   // Tracing--rename it to something indicative.
   String debugName() const;
 
 #ifndef NDEBUG
   String toString() const;
   String toTreeStringForThis() const;
@@ skipping 27 matching lines @@
       ShadowTreesTreatment = TreatShadowTreesAsDisconnected) const;
 
   Node* toNode() final;
 
   const AtomicString& interfaceName() const override;
   ExecutionContext* getExecutionContext() const final;
 
   void removeAllEventListeners() override;
   void removeAllEventListenersRecursively();
 
-  // Handlers to do/undo actions on the target node before an event is dispatched to it and after the event
-  // has been dispatched.  The data pointer is handed back by the preDispatch and passed to postDispatch.
+  // Handlers to do/undo actions on the target node before an event is
+  // dispatched to it and after the event has been dispatched.  The data pointer
+  // is handed back by the preDispatch and passed to postDispatch.
   virtual EventDispatchHandlingState* preDispatchEventHandler(Event*) {
     return nullptr;
   }
   virtual void postDispatchEventHandler(Event*, EventDispatchHandlingState*) {}
 
   void dispatchScopedEvent(Event*);
 
   virtual void handleLocalEvents(Event&);
 
   void dispatchSubtreeModifiedEvent();
@@ skipping 163 matching lines @@
   NodeRareData* rareData() const;
   NodeRareData& ensureRareData();
 
   void setHasCustomStyleCallbacks() {
     setFlag(true, HasCustomStyleCallbacksFlag);
   }
 
   void setTreeScope(TreeScope* scope) { m_treeScope = scope; }
 
   // isTreeScopeInitialized() can be false
-  // - in the destruction of Document or ShadowRoot where m_treeScope is set to null or
-  // - in the Node constructor called by these two classes where m_treeScope is set by TreeScope ctor.
+  // - in the destruction of Document or ShadowRoot where m_treeScope is set to
+  //   null or
+  // - in the Node constructor called by these two classes where m_treeScope is
+  //   set by TreeScope ctor.
   bool isTreeScopeInitialized() const { return m_treeScope; }
 
   void markAncestorsWithChildNeedsStyleRecalc();
 
   void setIsFinishedParsingChildren(bool value) {
     setFlag(value, IsFinishedParsingChildrenFlag);
   }
 
  private:
   // Gets nodeName without caching AtomicStrings. Used by
@@ skipping 108 matching lines @@
 }  // namespace blink
 
 #ifndef NDEBUG
 // Outside the WebCore namespace for ease of invocation from gdb.
 void showNode(const blink::Node*);
 void showTree(const blink::Node*);
 void showNodePath(const blink::Node*);
 #endif
 
 #endif  // Node_h