Add documentation for MemoryCoordinator-related primitives

base/memory/memory_coordinator_client.h

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_
 #define BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_
 
 #include "base/base_export.h"
 
 namespace base {
 
 // OVERVIEW:
 //
 // MemoryCoordinatorClient is an interface which a component can implement to
 // adjust "future allocation" and "existing allocation". For "future allocation"
 // it provides a callback to observe memory state changes, and for "existing
 // allocation" it provides a callback to purge memory.
 //
 // Unlike MemoryPressureListener, memory state changes are stateful. State
 // transitions are throttled to avoid thrashing; the exact throttling period is
 // platform dependent, but will be at least 5-10 seconds. When a state change
 // notification is dispatched, clients are expected to update their allocation
 // policies (e.g. setting cache limit) that persist for the duration of the
 // memory state. Note that clients aren't expected to free up memory on memory
 // state changes. Clients should wait for a separate purge request to free up
 // memory. Purging requests will be throttled as well.
-
+//
+// See //base/memory/memory_coordinator.md for the replacement plan.

[Ryan Sleevi, 2017/02/25 02:57:10]

I don't think memory_coordinator.md is really "the replacement plan", but rather
the "How to use them"

That is, it gives no information about how the replacement will look other than
there is a plan :)

+//
 // MemoryState is an indicator that processes can use to guide their memory
 // allocation policies. For example, a process that receives the throttled
 // state can use that as as signal to decrease memory cache limits.
 // NOTE: This enum is used to back an UMA histogram, and therefore should be
 // treated as append-only.
 enum class MemoryState : int {
   // The state is unknown.
   UNKNOWN = -1,
   // No memory constraints.
   NORMAL = 0,
@@ skipping 32 matching lines @@
   // any memory whose contents can be reproduced.
   virtual void OnPurgeMemory() {}
 
  protected:
   virtual ~MemoryCoordinatorClient() {}
 };
 
 }  // namespace base
 
 #endif  // BASE_MEMORY_MEMORY_COORDINATOR_CLIENT_H_