Add missing documentation for Allocator.h macros + EAGERLY_FINALIZE().

third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md

Index: third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md
diff --git a/third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md b/third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md
index 8a7abc56a84ccd036835109a2e530d043d572ef2..8891f5da6d649b8cd8abe6580c6bd3066d86ffdd 100644
--- a/third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md
+++ b/third_party/WebKit/Source/platform/heap/BlinkGCAPIReference.md
@@ -202,10 +202,40 @@ Especially, avoid defining a pre-finalizer in a class that can be allocated a lo
 
 ### EAGERLY_FINALIZE
 
-### DISALLOW_NEW_EXCEPT_PLACEMENT_NEW
+A class-level annotation to indicate that class instances that the GC have determined as unreachable, should be eagerly
+swept and finalized by the garbage collector, before the Blink thread (the mutator) resumes after a garbage
+collection. The C++ destructor runs as part of this step. The default sweeping behavior is incremental, sweeping
+pages as demanded by later heap allocations.
+
+Like for the pre-finalizer mechanism, an `EAGERLY_FINALIZE()`d class is allowed to touch other heap objects, which
+is sometimes required, but the main use case for eager finalization is to promptly let go of off-heap resources
+and associations, by unregistering and destructing those eagerly. If not done, these external references would
+otherwise attempt to unsafely access an effectively-dead object (pending lazy sweeping of its heap page.)
+
+`EAGERLY_FINALIZE()` solves the same problem as pre-finalizers, but it arguably fits more naturally with the host
+language's mechanism for finalization (C++ destructors.) One `EAGERLY_FINALIZE()` caveat is that the destructor
+is not allowed to touch another eagerly finalized object (their finalization ordering isn't deterministic) nor
+any pre-finalized objects. Choose the one you think best fits your need for prompt finalization.
 
 ### STACK_ALLOCATED
 
+Class level annotation that should be used if the object is only stack allocated; it disallows use
+of `operator new`. Any garbage-collected objects should be kept as `Member<T>` references, but you do not
+need to define a `trace()` method as they are on the stack, and automatically traced and kept alive should
+a conservative GC be required.
+
+### DISALLOW_NEW()
+
+Class-level annotation declaring the class a part object that cannot be separately allocated using `operator new`.
+If the class has `Member<T>` references, you need a `trace()` method which the object containing the `DISALLOW_NEW()`
+part object must call upon. The clang Blink GC plugin checks and enforces this.
+
+### DISALLOW_NEW_EXCEPT_PLACEMENT_NEW
+
+Class-level annotation allowing only the use of the placement `new` operator. This disallows general allocation of the
+object but allows putting the object as a value object in collections.  If the class has `Member<T>` references,
+you need to declare a `trace()` method. That trace method will be called automatically by the on-heap collections.
+
 ## Handles
 
 Class templates in this section are smart pointers, each carrying a pointer to an on-heap object (think of `RefPtr<T>`