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

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

 # Blink GC API reference
 
 This is a through document for Oilpan API usage.
 If you want to learn the API usage quickly, look at
 [this tutorial](https://docs.google.com/presentation/d/1XPu03ymz8W295mCftEC9KshH9Icxfq81YwIJQzQrvxo/edit#slide=id.p).
 If you're just interested in wrapper tracing,
 see [Wrapper Tracing Reference](../../bindings/core/v8/TraceWrapperReference.md).
 
 [TOC]
 
@@ skipping 184 matching lines @@
     Member<OtherClass> m_other;
 };
 ```
 
 Pre-finalizers have some implications on the garbage collector's performance: the garbage-collector needs to iterate
 all registered pre-finalizers at every GC. Therefore, a pre-finalizer should be avoided unless it is really necessary.
 Especially, avoid defining a pre-finalizer in a class that can be allocated a lot.
 
 ### EAGERLY_FINALIZE
 
+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
 
-### STACK_ALLOCATED
+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>`
 for `RefCounted<T>`). Collectively, they are called *handles*.
 
 On-heap objects must be retained by any of these, depending on the situation.
 
 ### Raw pointers
 
@@ skipping 236 matching lines @@
 };
 ```
 
 Please be very cautious if you want to use a heap collection from multiple threads. Reference to heap collections may be passed to another thread using CrossThreadPersistents, but *you may not modify the collection from the non-owner thread*. This is because modifications to collections may trigger backing store reallocations, and Oilpan's per thread heap requires that modifications to a heap happen on its owner thread.
 
 ### Weak collections
 
 You can put `WeakMember<T>` in heap collections except for `HeapVector` and `HeapDeque` which we do not support.
 
 During an Oilpan GC, the weak members that refernce a collected object will be removed from its heap collection, meaning the size of the collection will shrink and you do not have to check for null weak members when iterating through the collection.