Update sandbox::SeatbeltExtension documentation

Make it clear that Revoke() must be called after Consume(), which is
what the current DCEHCK in dtor checks. If an extension does not need to
be revoked, use ConsumePermanently().

BUG=510604
TEST=No functionality change

Change-Id: Ifee995ffdfc608e4ccc40bbbb4096511c561237a
Reviewed-on: https://chromium-review.googlesource.com/701274
Commit-Queue: Xiaohan Wang <xhwang@chromium.org>
Reviewed-by: Robert Sesek <rsesek@chromium.org>
Cr-Commit-Position: refs/heads/master@{#506520}

sandbox/mac/seatbelt_extension.cc

@@ -23,7 +23,7 @@ namespace sandbox {
 
 SeatbeltExtension::~SeatbeltExtension() {
   DCHECK(token_.empty() && handle_ == 0)
-      << "A SeatbeltExtension must be consumed or revoked.";
+      << "A SeatbeltExtension must be consumed permanently or revoked.";
 }
 
 // static

sandbox/mac/seatbelt_extension.h

@@ -25,6 +25,7 @@ class SeatbeltExtensionToken;
 class SEATBELT_EXPORT SeatbeltExtension {
  public:
   enum Type {
+    // Requires (allow file-read* (extension "com.apple.app-sandbox.read")).
     FILE_READ,
     // TODO(rsesek): Potentially support FILE_READ_WRITE, MACH and GENERIC
     // extension types.
@@ -50,8 +51,8 @@ class SEATBELT_EXPORT SeatbeltExtension {
   // Consumes the sandbox extension, giving the calling process access to the
   // resource for which the extension was issued. Returns true if the
   // extension was consumed and the resource access is now permitted, and
-  // false on error with the resource still denied. The extension can be
-  // revoked by the calling process.
+  // false on error with the resource still denied. The extension must be
+  // revoked by the calling process before being destructed.
   bool Consume();
 
   // Like Consume(), but makes it so that the extension cannot be revoked.