Add some comments to IOThreadExtensionFunction explaining its intended use.

chrome/browser/extensions/extension_function.h

 // Copyright (c) 2011 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 CHROME_BROWSER_EXTENSIONS_EXTENSION_FUNCTION_H_
 #define CHROME_BROWSER_EXTENSIONS_EXTENSION_FUNCTION_H_
 #pragma once
 
 #include <string>
 #include <list>
@@ skipping 260 matching lines @@
                          const NotificationDetails& details);
     UIThreadExtensionFunction* function_;
     NotificationRegistrar registrar_;
   };
 
   virtual void Destruct() const;
 
   scoped_ptr<RenderViewHostTracker> tracker_;
 };
 
-// Extension functions that run on the IO thread.
+// Extension functions that run on the IO thread. This type of function avoids
+// a roundtrip to and from the UI thread (because communication with the
+// extension process happens on the IO thread). It's intended to be used when
+// performance is critical (e.g. the webRequest API which can block network
+// requests). Generally, UIThreadExtensionFunction is more appropriate and will
+// be easier to use and interface with the rest of the browser.
 class IOThreadExtensionFunction : public ExtensionFunction {
  public:
   IOThreadExtensionFunction();
 
   virtual IOThreadExtensionFunction* AsIOThreadExtensionFunction() OVERRIDE;
 
   void set_ipc_sender(base::WeakPtr<ChromeRenderMessageFilter> ipc_sender,
                       int routing_id) {
     ipc_sender_ = ipc_sender;
     routing_id_ = routing_id;
@@ skipping 60 matching lines @@
  public:
   SyncIOThreadExtensionFunction();
 
   virtual void Run() OVERRIDE;
 
  protected:
   virtual ~SyncIOThreadExtensionFunction();
 };
 
 #endif  // CHROME_BROWSER_EXTENSIONS_EXTENSION_FUNCTION_H_