Update blink/renderer/README.md

This patch updates the readme to align with recent conversations
about what platform/, core/ and modules/ are and what they should be.

Change-Id: I2f4f0b50711cc2cd3cd455ad78c2fc5c96f53e1e
Reviewed-on: https://chromium-review.googlesource.com/1054190
Commit-Queue: Dmitry Gozman <dgozman@chromium.org>
Reviewed-by: Kentaro Hara <haraken@chromium.org>
Reviewed-by: Daniel Cheng <dcheng@chromium.org>
Reviewed-by: Jeremy Roman <jbroman@chromium.org>
Reviewed-by: Adithya Srinivasan <adithyas@chromium.org>
Cr-Commit-Position: refs/heads/master@{#558099}

third_party/blink/renderer/README.md

-# Blink directory structure
+## `blink/renderer` directory structure
 
-This document describes a high-level architecture of Blink's top-level directories.
+This document describes a high-level architecture of `blink/renderer`,
+which contains most of the Web Platform implementation, and runs exclusively
+in the renderer process.
+On the other hand, [`common/`](../common) and [`public/common`](../public/common)
+also run in the browser process.
 
-## core/ and modules/
+All code in `blink/renderer` is an implementation detail of Blink
+and should not be used outside of it. Use [Blink's public API](../public)
+in code outside of Blink.
 
-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/.
+### `core/`
 
-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/.
+The `core/` directory implements the essence of the Web Platform defined by specs
+and IDL interfaces. Due to historical reasons, `core/` contains a lot of features with
+complex inter-dependencies and hence can be perceived as a single monolithic entity.
 
-In terms of dependencies, modules/ can depend on core/.
-core/ cannot depend on modules/. modules/xxx/ can depend on modules/yyy/.
+### `modules/`
 
-## bindings/
+The `modules/` directory is a collection of self-contained, well-defined features
+of the Web Platform that are factored out of a monolithic `core/`. These features are:
+ - large, tens to hundreds of files, with rare exceptions;
+ - self-contained with fine-grained responsibilities and `README.md`;
+ - have dependencies outlined with DEPS explicitly;
+ - can depend on other features under `platform/`, `core/` or `modules/`,
+   forming a healthy dependency tree.
 
-bindings/ is a directory to put files that heavily use V8 APIs.
+`modules/` OWNERS are responsible for making sure only features
+that satisfy requirements above are added.
 
-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/.)
+For example, `modules/crypto` implements WebCrypto API.
+
+### `platform/`
+
+The `platform/` directory is a collection of lower level features of Blink that are factored
+out of a monolithic `core/`. These features follow the same principles as `modules/`,
+but with different dependencies allowed:
+ - large, tens to hundreds of files, with rare exceptions;
+ - self-contained with fine-grained responsibilities and `README.md`;
+ - have dependencies outlined with DEPS explicitly;
+ - can depend on other features under `platform/` (but not `core/` or `modules/`),
+   forming a healthy dependency tree.
+
+`platform/` OWNERS are responsible for making sure only features
+that satisfy requirements above are added.
+
+For example, `platform/scheduler` implements a task scheduler for all tasks
+posted by Blink, while `platform/wtf` implements Blink-specific containers
+(e.g., `WTF::Vector`, `WTF::HashTable`, `WTF::String`).
 
-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.
+### `core` vs `modules` vs `platform` split
 
-## platform/
+Note that specs do not have a notion of "core", "platform" or "modules".
+The distinction between them is for implementation
+convenience to avoid putting everything in a single `core/` entity
+(which decreases code modularity and increases build time):
+  - features that are tightly coupled with HTML, CSS and other fundamental parts
+    of DOM should go to `core/`;
+  - features which conceptually depend on the features from "core"
+    should go to `modules/`;
+  - features which the "core" depends upon should go to `platform/`.
+
+Note that some of these guidelines are violated (at the time of writing this),
+but the code should gradually change and eventually conform.
+
+### `bindings/`
+
+The `bindings/` directory contains files that heavily use V8 APIs.
+The rationale for splitting bindings out is: V8 APIs are complex, error-prone and
+security-sensitive, so we want to put V8 API usage separately from other code.
+
+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/`. Consult `bindings/` OWNERS when in doubt.
 
-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/.
+Note that over time `bindings/core` should move to `core/bindings` and become
+just a part of a larger "core".
 
-platform/wtf/ is a directory to implement Blink-specific containers
-(e.g., Vector, HashTable, String).
+All of the above applies to `bindings/modules` and `modules/`.
 
-In terms of dependencies, core/ and modules/ can depend on platform/.
-platform/ cannot depend on core/ and modules/.
+### `controller/`
 
-## controller/
+The `controller/` directory contains the system infrastructure
+that uses or drives Blink. Functionality that implements the Web Platform
+should not go to `controller/`, but instead reside in `platform/`, `core/`
+or `modules/`.
 
-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/.
+If the sole purpose of higher level functionality is to drive the Web Platform
+or to implement API for the embedder, it goes to `controller/`,
+however most of the features should go to other directories.
+Consult `controller/` OWNERS when in doubt.
 
-In terms of dependencies, controller/ can depend on core/ and modules/.
-core/ and modules/ cannot depend on controller/.
+In terms of dependencies, `controller/` can depend on `core/`, `platform/` and `modules/`,
+but not vice versa.
 
-## devtools/
+### `devtools/`
 
-devtools/ implements a client-side of the Chrome DevTools, including all JS &
-CSS to run the DevTools webapp.
+The `devtools/` directory contains a frontend of the Chrome DevTools,
+including the build scripts and DevTools webapp.
 
-In terms of dependencies, devtools/ is a stand-alone directory.
+In terms of dependencies, `devtools/` is a stand-alone directory.
 
-## build/
+### `build/`
 
-build/ contains scripts to build Blink.
+The `build/` directory contains scripts to build Blink.
 
-In terms of dependencies, build/ is a stand-alone directory.
+In terms of dependencies, `build/` is a stand-alone directory.
 
-## Directory dependencies
+## 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.
+- `public/web`
+- `controller/`
+- `modules/` and `bindings/modules`
+- `core/` and `bindings/core`
+- `platform/`
+- `public/platform`
+- `public/common`
+- `//base`, V8 etc.
 
 See [this diagram](https://docs.google.com/document/d/1yYei-V76q3Mb-5LeJfNUMitmj6cqfA5gZGcWXoPaPYQ/edit).
 
-devtools/ and build/ are stand-alone directories.
+`devtools/` and `build/` are stand-alone directories.
 
-## Type dependencies
+### Type dependencies
 
-core/, modules/, bindings/, platform/ and controller/ can use std:: types and
+`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).
+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/audit_non_blink_usage.py).
 
-## Mojo
+### Mojo
 
-core/, modules/, bindings/, platform/ and controller/ can use Mojo and
-directly talk with the browser process. This allows removal of unnecessary
+`core/`, `modules/`, `bindings/`, `platform/` and `controller/` can use Mojo and
+directly talk to the browser process. This allows removal of unnecessary
 public APIs and abstraction layers and it is highly recommended.
 
 ## Contact