Add WebKit/Source/README.md

Bug: 784252
Change-Id: Iaf2c709ddd12134382a621205d3b34b08474f86e
Reviewed-on: https://chromium-review.googlesource.com/823863
Commit-Queue: Kentaro Hara <haraken@chromium.org>
Reviewed-by: Philip Jägenstedt <foolip@chromium.org>
Reviewed-by: Daniel Cheng <dcheng@chromium.org>
Cr-Commit-Position: refs/heads/master@{#524321}

third_party/WebKit/Source/OWNERS

 per-file DEPS=dcheng@chromium.org
 per-file DEPS=haraken@chromium.org
 per-file DEPS=jbroman@chromium.org
+per-file README.md=haraken@chromium.org
+

third_party/WebKit/Source/README.md

+# Blink directory structure
+
+This document describes a high-level architecture of Blink's top-level directories.
+
+## core/ and modules/
+
+core/ and modules/ are directories to implement web platform features
+defined in the specs. IDL files and their implementations should go to
+core/ and modules/.
+
+Note that the specs do not have a notion of "core" and "modules".
+The distinction between core/ and modules/ is for implementational convenience
+to avoid putting everything in core/ (which decreases code modularity and
+increases build time). Basically web platform features that are tighly coupled with
+HTML, CSS and other fundamental parts of DOM should go to core/.
+Other web platform features should go to modules/.
+
+In terms of dependencies, modules/ can depend on core/.
+core/ cannot depend on modules/. modules/xxx/ can depend on modules/yyy/.
+
+## bindings/
+
+bindings/ is a directory to put files that heavily use V8 APIs.
+
+In terms of dependencies, bindings/core/ and core/ are in the same link unit.
+The only difference is how heavily they are using V8 APIs.
+If a given file is using a lot of V8 APIs, it should go to bindings/core/.
+Otherwise, it should go to core/.
+(The same principle applies to bindings/modules/ and modules/.)
+
+The rationale for this split is: V8 APIs are complex, error-prone and
+security-sensitive, so we want to put V8 API usages in one directory.
+
+## platform/
+
+platform/ is a directory to implement low-level libraries of Blink.
+For example, platform/scheduler/ implements a task scheduler for all tasks
+posted by Blink. To avoid putting everything in core/ and modules/,
+consider factoring out low-level functionalities to platform/.
+
+platform/wtf/ is a directory to implement Blink-specific containers
+(e.g., Vector, HashTable, String).
+
+In terms of dependencies, core/ and modules/ can depend on platform/.
+platform/ cannot depend on core/ and modules/.
+
+## controller/
+
+controller/ is a directory to implement high-level functionalities
+on top of core/ and modules/. Functionalities that use or drive Blink
+should go to controller/.
+
+In terms of dependencies, controller/ can depend on core/ and modules/.
+core/ and modules/ cannot depend on controller/.
+
+## devtools/
+
+devtools/ implements a client-side of the Chrome DevTools, including all JS &
+CSS to run the DevTools webapp.
+
+In terms of dependencies, devtools/ is a stand-alone directory.
+
+## build/
+
+build/ contains scripts to build Blink.
+
+In terms of dependencies, build/ is a stand-alone directory.
+
+## Directory dependencies
+
+Dependencies only flow in the following order:
+
+- public/web/
+- controller/
+- modules/ and bindings/modules/
+- core/ and bindings/core/
+- platform/
+- public/platform/, //base/, V8 etc.
+
+See [this diagram](https://docs.google.com/document/d/1yYei-V76q3Mb-5LeJfNUMitmj6cqfA5gZGcWXoPaPYQ/edit).
+
+devtools/ and build/ are stand-alone directories.
+
+## Type dependencies
+
+core/, modules/, bindings/, platform/ and controller/ can use std:: types and
+types defined in Chromium. The philosophy is that we should
+share as much code between Chromium and Blink as possible.
+
+However, there are a couple of types that really need to be optimized
+for Blink's workload (e.g., Vector, HashTable, Bind, AtomicString).
+These types are defined in platform/wtf/. If there is an equivalent in
+platform/wtf/, Blink must use the type in platform/wtf/ instead of the type
+defined in Chromium. For example, Blink should not use std::vector
+(except places where a conversion between std::vector and WTF::Vector is needed).
+
+To prevent use of random types, we control allowed types by whitelisting
+them in DEPS and a [presubmit script](../Tools/Scripts/audit-non-blink-usage.py).
+
+## Mojo
+
+core/, modules/, bindings/, platform/ and controller/ can use Mojo and
+directly talk with the browser process. This allows removal of unnecessary
+public APIs and abstraction layers and it is highly recommended.
+
+## Contact
+
+If you have any questions about the directory architecture and dependencies,
+reach out to platform-architecture-dev@chromium.org!
+

third_party/WebKit/public/README.md

@@ -31,15 +31,31 @@ runs. Rather than communicating directly with the underlying operating system,
 Blink is designed to run in a sandbox and interacts with the operating system
 via the platform API. The central interface in this part of the API is
 Platform, which is a pure virtual interface from which Blink obtains many other
-interfaces.
+interfaces. public/platform/ is implemented by WebKit/Source/platform/exported/.
 
 The public/web directory defines an interface to Blink's implementation of the
 web platform, including the Document Object Model (DOM). The central interface
 in this part of the API is WebView, which is a good starting point for
-exploring the API.
+exploring the API. public/web/ is implemented by
+WebKit/Source/{core,modules,controller}/exported/.
 
 Note that public/platform should not depend on public/web.
 
+Notes
+-----
+
+As mentioned above, conceptually public/platform/ and public/web/ should be
+used as follows:
+
+  - public/platform/ is implemented by the underlying functionalities and used by Blink
+  - public/web/ is implemented by Blink and used by Chromium
+
+In reality, however, they are sometimes abused. Due to the dependency constraint
+(public/web/ => controller/ => modules/ => core/ => platform/ => public/platform/),
+people sometimes define classes in public/platform/ or public/web/ just because
+that place is more convenient. This is already happening in many places but keep
+the concept in mind.
+
 Basic Types
 -----------