Make it clear that base::FileDescriptor::auto_close is purely advisory.

base/file_descriptor_posix.h

 // Copyright (c) 2006-2009 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_FILE_DESCRIPTOR_POSIX_H_
 #define BASE_FILE_DESCRIPTOR_POSIX_H_
 
 #include "base/files/file.h"
 #include "base/files/scoped_file.h"
 
 namespace base {
 
 // -----------------------------------------------------------------------------
 // We introduct a special structure for file descriptors in order that we are
 // able to use template specialisation to special-case their handling.
 //
-// WARNING: (Chromium only) There are subtleties to consider if serialising
-// these objects over IPC. See comments in ipc/ipc_message_utils.h
-// above the template specialisation for this structure.
+// IMPORTANT: This is primarily intended for use when sending file descriptors
+// over IPC. Even if |auto_close| is true, base::FileDescriptor does NOT close()
+// |fd| when going out of scope. Instead, a consumer of a base::FileDescriptor
+// must invoke close() on |fd| if |auto_close| is true.
+//
+// In the case of IPC, the the IPC subsystem knows to close() |fd| after sending
+// a message that contains a base::FileDescriptor if auto_close == true. On the
+// other end, the receiver must make sure to close() |fd| after its finished

[Nico, 2015/08/18 22:32:30]

s/its/it has/

[dcheng, 2015/08/18 23:30:14]

Done.

+// processing the IPC message. See the IPC::ParamTraits<> specialization in
+// ipc/ipc_message_utils.h for all the details.
+//
+// TL;DR: I'm a sign, not a cop. Don't use this class unless you absolutely have

[Nico, 2015/08/18 22:32:30]

remove this paragraph

[dcheng, 2015/08/18 23:30:14]

Aww, I really wanted to find a legitimate way to use this phrase in Chrome =)

+// to.
 // -----------------------------------------------------------------------------
 struct FileDescriptor {
   FileDescriptor() : fd(-1), auto_close(false) {}
 
   FileDescriptor(int ifd, bool iauto_close) : fd(ifd), auto_close(iauto_close) {
   }
 
   FileDescriptor(File file) : fd(file.TakePlatformFile()), auto_close(true) {}
   explicit FileDescriptor(ScopedFD fd) : fd(fd.release()), auto_close(true) {}
 
@@ skipping 13 matching lines @@
   int fd;
   // If true, this file descriptor should be closed after it has been used. For
   // example an IPC system might interpret this flag as indicating that the
   // file descriptor it has been given should be closed after use.
   bool auto_close;
 };
 
 }  // namespace base
 
 #endif  // BASE_FILE_DESCRIPTOR_POSIX_H_