Make it clear that base::FileDescriptor::auto_close is purely advisory.
close() the fd. Or don't.
I'm a sign, not a cop.
BUG=522207
Review URL: https://codereview.chromium.org/1293153007
Cr-Commit-Position: refs/heads/master@{#344178}
diff --git a/base/file_descriptor_posix.h b/base/file_descriptor_posix.h
index 376ad39..2a36611 100644
--- a/base/file_descriptor_posix.h
+++ b/base/file_descriptor_posix.h
@@ -14,9 +14,16 @@
// 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 it has finished
+// processing the IPC message. See the IPC::ParamTraits<> specialization in
+// ipc/ipc_message_utils.h for all the details.
// -----------------------------------------------------------------------------
struct FileDescriptor {
FileDescriptor() : fd(-1), auto_close(false) {}
