Update and fill up wtf/README.md with a proper introduction to WTF.

third_party/WebKit/Source/platform/wtf/README.md

Index: third_party/WebKit/Source/platform/wtf/README.md
diff --git a/third_party/WebKit/Source/platform/wtf/README.md b/third_party/WebKit/Source/platform/wtf/README.md
index e61a5014f0d6bbc169d9331187148bbd547af52a..4ec1d6e82573ef215af94a98f95b404c0bf24e16 100644
--- a/third_party/WebKit/Source/platform/wtf/README.md
+++ b/third_party/WebKit/Source/platform/wtf/README.md
@@ -1,14 +1,107 @@
-# platform/wtf
-
-This is the location where all the files under Source/wtf will be moved
-eventually. See
-[the proposal](https://docs.google.com/document/d/1shS1IZe__auYxjm9FhPbTY2P01FbNTMYRh-nen5gkDo/edit?usp=sharing)
-and
-[the design doc](https://docs.google.com/document/d/1JK26H-1-cD9-s9QLvEfY55H2kgSxRFNPLfjs049Us5w/edit?usp=sharing)
-regarding the relocation project. For the project's progress, see
-[bug 691465](https://bugs.chromium.org/p/chromium/issues/detail?id=691465).
-
-During the project, files in wtf/ are moved to platform/wtf incrementally, and
-redirection headers will be placed in wtf/. So nothing should break in the
-meantime. You can continue including WTF headers like `#include "wtf/Xxx.h"`
-till the next announce in blink-dev.
+# WTF (Web Template Framework)
+
+WTF is a base library for Blink providing a variety of basic functionalities,
+like containers, string libraries, reference counting mechanisms, functors,
+threading primitives etc.
+
+WTF's mission is to power and support all other Blink modules by providing
+fast, reliable, user-friendly and secure generic primitives.
+
+Dependency-wise, WTF cannot depend on any other Blink modules, including

[haraken, 2017/04/20 13:45:13]

"modules" is confusing with modules/.

[Yuta Kitamura, 2017/04/21 09:26:41]

Done.

+other files under platform/, since WTF is a module that can be referred from
+anywhere in Blink. WTF basically can only depend on [base], so that we can
+bridge functionalities of base to other Blink modules.
+

[haraken, 2017/04/20 13:45:13]

Also let's explain the relationship between base/ and wtf/ more.

- We should share as much code between base/ and wtf/ as possible. However, we
are not planning to move everything to base/ because Blink needs primitives
highly optimized for its workload. Chromium and Blink sometimes have a different
assumption about performance, memory and code health.

- Since core/ and modules/ cannot use base/, we need to define a thin proxy
wrapper in wtf/.

[Yuta Kitamura, 2017/04/21 09:26:41]

Done.

+## Library catalog
+
+The below is a list of major libraries. For a complete list, look at
+[the directory listing].
+
+* **Containers**
+
+  [Vector], [HashSet], [HashMap], [Deque]
+
+* **Strings**
+
+  [String], [AtomicString], [StringBuilder], [CString]
+
+* **Reference counting**
+
+  [RefCounted], [RefPtr]
+
+* **Memory**
+
+  [PtrUtil.h] (`std::unique_ptr<>` utilities),
+  [Allocator.h] (memory placement macros)
+
+* **Functors, binding**
+
+  [Functional.h]
+
+* **Threading**
+
+  [Threading.h], [ThreadingPrimitives.h]
+
+* **Compile-time switch macros**
+
+  [Compiler.h] (e.g. `COMPILER(GCC)`),
+  [CPU.h] (e.g. `CPU(X86_64)` or `CPU(64BIT)`),
+  [build_config.h] (e.g. `OS(WIN)`)
+
+* **Miscellaneous**
+
+  [Noncopyable.h] (`WTF_MAKE_NONCOPYABLE`),
+  [StdLibExtras.h] (`DEFINE_STATIC_LOCAL` etc.),
+  [CurrentTime.h],
+  [CryptographicallyRandomNumber.h],
+  [AutoReset.h],
+  [Optional.h]
+
+## History
+
+The name WTF first [appeared in 2006][1], as a replacement of its older name
+KXMLCore. At that point, there were already plenty of libraries we see today.
+For example, you can see [the initial implementation of `Vector`][2] was landed
+in 2006, replacing several manual array allocations and deallocations(!).
+
+If you dig the repository a bit more, you can find the original version of
+Assertions.h was [committed back in 2002][3]. This is probably the oldest
+library that we can find from the repository history.
+
+As you see, pretty much everything that we have today in WTF was created in
+the WebKit era. WTF was initially under the directory Source/JavaScriptCore,
+but it moved to Source/WTF/wtf in 2011-2012, then to Source/wtf in 2013.
+
+Blink forked WebKit in 2013. In 2017, the directory finally [moved to the
+current location][4] Source/platform/wtf.
+
+[the directory listing]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/
+[base]: https://cs.chromium.org/chromium/src/base/
+[Vector]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Vector.h

[haraken, 2017/04/20 13:45:13]

I'd prefer dropping these links since it wouldn't be that useful and would be
easily out-dated.

[Yuta Kitamura, 2017/04/21 09:26:41]

I would argue that those links are worth having because:
(1) they are very useful for those finding a functionality in WTF, and
(2) outdated links are only as bad as no links (and fixing is easy).

+[HashSet]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/HashSet.h
+[HashMap]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/HashMap.h
+[Deque]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Deque.h
+[String]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/text/WTFString.h
+[AtomicString]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/text/AtomicString.h
+[StringBuilder]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/text/StringBuilder.h
+[CString]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/text/CString.h
+[RefCounted]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/RefCounted.h
+[RefPtr]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/RefPtr.h
+[PtrUtil.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/PtrUtil.h
+[Allocator.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Allocator.h
+[Functional.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Functional.h
+[Threading.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Threading.h
+[ThreadingPrimitives.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/ThreadingPrimitives.h
+[Compiler.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Compiler.h
+[CPU.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/CPU.h
+[build_config.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/build_config.h
+[Noncopyable.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Noncopyable.h
+[StdLibExtras.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/StdLibExtras.h
+[CurrentTime.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/CurrentTime.h
+[CryptographicallyRandomNumber.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/CryptographicallyRandomNumber.h
+[AutoReset.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/AutoReset.h
+[Optional.h]: https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/wtf/Optional.h
+[1]: https://chromium.googlesource.com/chromium/src/+/e372c152fc6e57743ebc508fe17f6eb131b4ff8d
+[2]: https://chromium.googlesource.com/chromium/src/+/547a6ca360a56fbee3d5ea4a71ba18f91622455c
+[3]: https://chromium.googlesource.com/chromium/src/+/478890427ee03fd88e6f0f58ee8220512044bed9/third_party/WebKit/WebCore/kwq/KWQAssertions.h
+[4]:https://docs.google.com/document/d/1JK26H-1-cD9-s9QLvEfY55H2kgSxRFNPLfjs049Us5w/edit?usp=sharing