NaCl: Expand comment about PpapiHostMsg_OpenResource in ppapi_messages.h

ppapi/proxy/ppapi_messages.h

 // Copyright (c) 2012 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.
 
 // Multiply-included message header, no traditional include guard.
 #include <map>
 #include <string>
 #include <vector>
 
 #include "base/basictypes.h"
@@ skipping 866 matching lines @@
 // Reply to PpapiMsg_CreateChannel. The handle will be NULL if the channel
 // could not be established. This could be because the IPC could not be created
 // for some weird reason, but more likely that the plugin failed to load or
 // initialize properly.
 IPC_MESSAGE_CONTROL1(PpapiHostMsg_ChannelCreated,
                      IPC::ChannelHandle /* handle */)
 
 // Notify the renderer that the PPAPI channel gets ready in the plugin.
 IPC_MESSAGE_CONTROL0(PpapiHostMsg_StartupInitializationComplete)
 
-// Calls renderer to open a resource file for nacl_irt_open_resource().
+// This is sent from a nexe (NaCl untrusted code) to the renderer, to open a
+// file listed in a NaCl manifest file (NMF).  It is part of the
+// implementation of open_resource(), which is defined in NaCl's irt.h.
+//
+// This call returns a read-only file handle from the renderer.  When using
+// validation caching, this handle is not used: The NaCl loader process will
+// reacquire the handle from the more-trusted browser process via
+// NaClProcessMsg_ResolveFileToken, passing the token values returned here.
+//
+// Note that the open_resource() interface is not a PPAPI interface (in the
+// sense that it's not defined in ppapi/c/), but this message is defined here
+// in ppapi_messages.h (rather than in components/nacl/) because half of the
+// implementation of open_resource() lives in ppapi/nacl_irt/, and because
+// this message must be processed by ppapi/proxy/nacl_message_scanner.cc.
 IPC_SYNC_MESSAGE_CONTROL1_3(PpapiHostMsg_OpenResource,
                             std::string /* key */,
                             ppapi::proxy::SerializedHandle /* fd */,
                             uint64_t /* file_token_lo */,
                             uint64_t /* file_token_hi */)
 
 // Logs the given message to the console of all instances.
 IPC_MESSAGE_CONTROL4(PpapiHostMsg_LogWithSource,
                      PP_Instance /* instance */,
                      int /* log_level */,
@@ skipping 1472 matching lines @@
                      std::vector<ppapi::HostResource> /* buffers */,
                      uint32_t /* buffer_size */)
 IPC_MESSAGE_CONTROL1(PpapiPluginMsg_VideoCapture_OnStatus,
                      uint32_t /* status */)
 IPC_MESSAGE_CONTROL1(PpapiPluginMsg_VideoCapture_OnError,
                      uint32_t /* error */)
 IPC_MESSAGE_CONTROL1(PpapiPluginMsg_VideoCapture_OnBufferReady,
                      uint32_t /* buffer */)
 
 #endif  // !defined(OS_NACL) && !defined(NACL_WIN64)