Add documentation for the chrome.sockets API and manifest key.

chrome/common/extensions/api/sockets_tcp.idl

 // Copyright 2013 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.
 
 // Use the <code>chrome.sockets.tcp</code> API to send and receive data over the
 // network using TCP connections. This API supersedes the TCP functionality
-// previously found in the <code>chrome.socket</code> API. Note that the socket
-// ids created from this namespace are not compatible with ids created in other
-// namespaces.
+// previously found in the <code>chrome.socket</code> API.
 namespace sockets.tcp {
   // The socket properties specified in the <code>create</code> or
   // <code>update</code> function. Each property is optional. If a property
   // value is not specified, a default value is used when calling
   // <code>create</code>, or the existing value if preserved when calling
   // <code>update</code>.
   dictionary SocketProperties {
     // Flag indicating if the socket is left open when the event page of
     // the application is unloaded (see
     // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App
     // Lifecycle</a>). The default value is "false." When the application is
     // loaded, any sockets previously opened with persistent=true can be fetched
     // with <code>getSockets</code>.
     boolean? persistent;
 
     // An application-defined string associated with the socket.
     DOMString? name;
 
     // The size of the buffer used to receive data. The default value is 4096.
     long? bufferSize;
   };
 
   // Result of <code>create</code> call.
   dictionary CreateInfo {
-    // The ID of the newly created socket.
+    // The ID of the newly created socket. Note that socket IDs created from
+    // this API are not compatible with socket IDs created from other APIs, such
+    // as the deprecated <code>$ref:socket</code> API.
     long socketId;
   };
 
   // Callback from the <code>create</code> method.
   // |createInfo| : The result of the socket creation.
   callback CreateCallback = void (CreateInfo createInfo);
 
   // Callback from the <code>connect</code> method.
   // |result| : The result code returned from the underlying network call.
   // A negative value indicates an error.
@@ skipping 198 matching lines @@
     static void onReceive(ReceiveInfo info);
 
     // Event raised when a network error occured while the runtime was waiting
     // for data on the socket address and port. Once this event is raised, the
     // socket is set to <code>paused</code> and no more <code>onReceive</code>
     // events are raised for this socket.
     // |info| : The event data.
     static void onReceiveError(ReceiveErrorInfo info);
   };
 };