Complete breakup of Introduction.md

Author: stwrt

Sources/WebKit/WebKit.docc/Build&Debug/Build.md

@@ -124,3 +124,18 @@ run-minibrowser --debug --wpe
 
 Pass one of `--gtk`, `--jsc-only`, or `--wpe` to indicate the port to use.
 
+## Fixing mysterious build or runtime errors after Xcode upgrades
+
+If you see mysterious build failures or if you’ve switched to a new version of
+macOS or Xcode, delete the `WebKitBuild` directory.
+`make clean` may not delete all the relevant files,
+and building after doing that without deleting the `WebKitBuild` directory may result in mysterious build or dyld errors.
+
+## Building with Address Sanitizer to investigate memory corruption bugs
+
+To build [Address Sanitizer](https://en.wikipedia.org/wiki/AddressSanitizer) or ASan builds to analyze security bugs,
+run `Tools/Scripts/set-webkit-configuration --asan --release`.
+This will enable ASan build. If want to attach a debugger, you can also specify `--debug` instead of `--release`.
+Once you don’t need to build or run ASan anymore, you can specify `--no-asan` in place of `--asan` to disable ASan.
+Note that this configuration is saved by creating a file called Asan in the WebKitBuild directory,
+so if you are trying to do a clean Asan build by deleting the build directory you need to rerun this command.

Sources/WebKit/WebKit.docc/Build&Debug/DebuggingWithXcode.md

@@ -2,6 +2,35 @@
 
 Debugging with the Xcode IDE
 
+## Overview
+
+You can also use Xcode to build & debug WebKit. Open `WebKit.xcworkspace` at the top level directory.
+
+In order to make Xcode use build files built by `make` command above,
+go to File > Workspace Settings... > Advanced... > Custom > Relative to Workspace
+and adjust the relative paths of Products and Intermediates to point to `WebKitBuild` directory.
+![Screenshot of Xcode Workspace Settings](xcode-workspace-settings.png)
+![Screenshot of Xcode Workspace Settings - Advanced Build Location](xcode-workspace-build-location.png)
+Note that debugging WebCore code typically requires attaching to the relevant WebContent process,
+not the application process, which is mostly running code in [Source/WebKit/UIProcess](https://github.com/WebKit/WebKit/tree/main/Source/WebKit/UIProcess).
+Depending on what you’re debugging, you’d have to attach & debug different processes in the coalition.
+
+You may find it useful to use the debug helpers under `Tools/lldb/lldb_webkit.py`.
+This can be added to `~/.lldbinit` for automatic loading into LLDB on launch by adding the line `command script import {Path to WebKit}/Tools/lldb/lldb_webkit.py`.
+For more details, see the Wiki article on [lldb formatters](https://trac.webkit.org/wiki/lldb%20formatters).
+
+When debugging a debug build in LLDB, there are also a few functions that can be called on objects that will dump debugging info.
+
+* RenderObject
+    * showNodeTree()
+    * showLineTree()
+    * showRenderTree()
+* Node
+    * showTree()
+    * showNodePath()
+    * showTreeForThis()
+    * showNodePathForThis()
+
 ## Debugging Layout Tests
 
 The easiest way to debug a layout test is with WebKitTestRunner or DumpRenderTree.

Sources/WebKit/WebKit.docc/Build&Debug/Tests.md

@@ -0,0 +1,19 @@
+# Adding JS APIs
+
+## Overview
+
+To introduce a new JavaScript API in [WebCore](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/), 
+first identify the directory under which to implement this new API, and introduce corresponding Web IDL files (e.g., "dom/SomeAPI.idl").
+
+New IDL files should be listed in [Source/WebCore/DerivedSources.make](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/DerivedSources.make)
+so that the aforementioned perl script can generate corresponding JS*.cpp and JS*.h files.
+Add these newly generated JS*.cpp files to [Source/WebCore/Sources.txt](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Sources.txt)
+in order for them to be compiled.
+
+Also, add the new IDL file(s) to [Source/WebCore/CMakeLists.txt](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/CMakeLists.txt).
+
+Remember to add these files to [WebCore's Xcode project](https://github.com/WebKit/WebKit/tree/main/Source/WebCore/WebCore.xcodeproj) as well.
+
+For example, [this commit](https://github.com/WebKit/WebKit/commit/cbda68a29beb3da90d19855882c5340ce06f1546)
+introduced [`IdleDeadline.idl`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/IdleDeadline.idl)
+and added `JSIdleDeadline.cpp` to the list of derived sources to be compiled.

Sources/WebKit/WebKit.docc/GettingStarted/Introduction.md

@@ -265,3 +265,88 @@ Because `WeakHashMap` does not get notified when the referenced object is delete
 the users / owners of `WeakHashMap` are still responsible for deleting the relevant entries from the map.
 Otherwise, the memory space used by `WeakPtrImpl` and its value will not be free'ed up until
 next rehash or amortized cleanup cycle arrives (based on the total number of read or write operations).
+
+## Reference Counting of DOM Nodes
+
+[`Node`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Node.h) is a reference counted object but with a twist.
+It has a [separate boolean flag](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/Node.h#L832)
+indicating whether it has a [parent](https://dom.spec.whatwg.org/#concept-tree-parent) node or not.
+A `Node` object is [not deleted](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/Node.h#L801)
+so long as it has a reference count above 0 or this boolean flag is set.
+The boolean flag effectively functions as a `RefPtr` from a parent `Node`
+to each one of its [child](https://dom.spec.whatwg.org/#concept-tree-child) `Node`.
+We do this because `Node` only knows its [first child](https://dom.spec.whatwg.org/#concept-tree-first-child)
+and its [last child](https://dom.spec.whatwg.org/#concept-tree-last-child)
+and each [sibling](https://dom.spec.whatwg.org/#concept-tree-sibling) nodes are implemented
+as a [doubly linked list](https://en.wikipedia.org/wiki/Doubly_linked_list) to allow
+efficient [insertion](https://dom.spec.whatwg.org/#concept-node-insert)
+and [removal](https://dom.spec.whatwg.org/#concept-node-remove) and traversal of sibling nodes.
+
+Conceptually, each `Node` is kept alive by its root node and external references to it,
+and we use the root node as an opaque root of each `Node`'s JS wrapper.
+Therefore the JS wrapper of each `Node` is kept alive as long as either the node itself
+or any other node which shares the same root node is visited by the garbage collector.
+
+On the other hand, a `Node` does not keep its parent or any of its
+[shadow-including ancestor](https://dom.spec.whatwg.org/#concept-shadow-including-ancestor) `Node` alive
+either by reference counting or via the boolean flag even though the JavaScript API requires this to be the case.
+In order to implement this DOM API behavior,
+WebKit [will create](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/bindings/js/JSNodeCustom.cpp#L174)
+a JS wrapper for each `Node` which is being removed from its parent if there isn't already one.
+A `Node` which is a root node (of the newly removed [subtree](https://dom.spec.whatwg.org/#concept-tree)) is an opaque root of its JS wrapper,
+and the garbage collector will visit this opaque root if there is any JS wrapper in the removed subtree that needs to be kept alive.
+In effect, this keeps the new root node and all its [descendant](https://dom.spec.whatwg.org/#concept-tree-descendant) nodes alive
+if the newly removed subtree contains any node with a live JS wrapper, preserving the API contract.
+
+It's important to recognize that storing a `Ref` or a `RefPtr` to another `Node` in a `Node` subclass
+or an object directly owned by the Node can create a [reference cycle](https://en.wikipedia.org/wiki/Reference_counting#Dealing_with_reference_cycles),
+or a reference that never gets cleared.
+It's not guaranteed that every node is [disconnected](https://dom.spec.whatwg.org/#connected)
+from a [`Document`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Document.h) at some point in the future,
+and some `Node` may always have a parent node or a child node so long as it exists.
+Only permissible circumstances in which a `Ref` or a `RefPtr` to another `Node` can be stored
+in a `Node` subclass or other data structures owned by it is if it's temporally limited.
+For example, it's okay to store a `Ref` or a `RefPtr` in
+an enqueued [event loop task](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/EventLoop.h#L69).
+In all other circumstances, `WeakPtr` should be used to reference another `Node`,
+and JS wrapper relationships such as opaque roots should be used to preserve the lifecycle ties between `Node` objects.
+
+It's equally crucial to observe that keeping C++ Node object alive by storing `Ref` or `RefPtr`
+in an enqueued [event loop task](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/EventLoop.h#L69)
+does not keep its JS wrapper alive, and can result in the JS wrapper of a conceptually live object to be erroneously garbage collected.
+To avoid this problem, use [`GCReachableRef`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/GCReachableRef.h) instead
+to temporarily hold a strong reference to a node over a period of time.
+For example, [`HTMLTextFormControlElement::scheduleSelectEvent()`](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/html/HTMLTextFormControlElement.cpp#L547)
+uses `GCReachableRef` to fire an event in an event loop task:
+```cpp
+void HTMLTextFormControlElement::scheduleSelectEvent()
+{
+    document().eventLoop().queueTask(TaskSource::UserInteraction, [protectedThis = GCReachableRef { *this }] {
+        protectedThis->dispatchEvent(Event::create(eventNames().selectEvent, Event::CanBubble::Yes, Event::IsCancelable::No));
+    });
+}
+```
+
+Alternatively, we can make it inherit from an [active DOM object](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/ActiveDOMObject.h),
+and use one of the following functions to enqueue a task or an event:
+ - [`queueTaskKeepingObjectAlive`](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/ActiveDOMObject.h#L107)
+ - [`queueCancellableTaskKeepingObjectAlive`](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/ActiveDOMObject.h#L115)
+ - [`queueTaskToDispatchEvent`](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/ActiveDOMObject.h#L124)
+ - [`queueCancellableTaskToDispatchEvent`](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/ActiveDOMObject.h#L130)
+
+[`Document`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Document.h) node has one more special quirk
+because every [`Node`](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/dom/Node.h) can have access to a document
+via [`ownerDocument` property](https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument)
+whether Node is [connected](https://dom.spec.whatwg.org/#connected) to the document or not.
+Every document has a regular reference count used by external clients and
+[referencing node count](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/Document.h#L2093).
+The referencing node count of a document is the total number of nodes whose `ownerDocument` is the document.
+A document is [kept alive](https://github.com/WebKit/WebKit/blob/297c01a143f649b34544f0cb7a555decf6ecbbfd/Source/WebCore/dom/Document.cpp#L749)
+so long as its reference count and node referencing count is above 0.
+In addition, when the regular reference count is to become 0,
+it clears various states including its internal references to owning Nodes to sever any reference cycles with them.
+A document is special in that sense that it can store `RefPtr` to other nodes.
+Note that whilst the referencing node count acts like `Ref` from each `Node` to its owner `Document`,
+storing a `Ref` or a `RefPtr` to the same document or any other document will create
+a [reference cycle](https://en.wikipedia.org/wiki/Reference_counting#Dealing_with_reference_cycles)
+and should be avoided unless it's temporally limited as noted above.

Sources/WebKit/WebKit.docc/InDepth/AddingNewJSApi.md

@@ -1,4 +1,4 @@
-# WebKit's Build System
+# Build System
 
 An overview of how the WebKit build system is structured.
 

Sources/WebKit/WebKit.docc/InDepth/JSWrappers.md

@@ -0,0 +1,24 @@
+# Continuous Integration
+
+## Overview
+
+WebKit’s CI ([continuous integration](https://en.wikipedia.org/wiki/Continuous_integration)) infrastructure is located at [build.webkit.org](https://build.webkit.org/)).
+
+[build.webkit.org](https://build.webkit.org/) will build and test commits from WebKit in the chronological order
+and report test results to [results.webkit.org](https://results.webkit.org/).
+Due to the chronological ordering, results could be a few hours behind during the work week.
+
+
+We also have a dashboard to monitor the health of [build.webkit.org](https://build.webkit.org/)
+at [build.webkit.org/dashboard](https://build.webkit.org/dashboard/).
+If you observe that some bots are offline, or otherwise not processing your patch,
+please notify [[email protected]](mailto:[email protected]).
+
+This dashboard isn't great for investigating individual test failures,
+[results.webkit.org](https://results.webkit.org/) is a better tool for such investigations.
+It keeps track of individual test status by configuration over time.
+You can search individual tests by name or look at the historical results of entire test suites.
+These results will link back to the test runs in Buildbot which are associated with a specific failure.
+See layout tests section for more details on how to use these tools to investigate test failures observed on bots.
+
+FIXME: Add a section about downloading build products from build.webkit.org.

Sources/WebKit/WebKit.docc/InDepth/MemoryManagement.md

@@ -0,0 +1,11 @@
+# Todo
+
+Articles that need to be written.
+
+## Overview
+
+| Topic | Description |
+| ----- | ----------- |
+| Inserting or Removing DOM Nodes | FIXME: Talk about how a node insertion or removal works. |
+| Understanding Style and Render Tree | FIXME: Describe rendering/layers/compositing |
+| Security Model of Web | For starters, refer to https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy. FIXME: Write this section. |