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

chrome/common/extensions/api/sockets_tcp_server.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.tcpServer</code> API to create server
 // applications 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.tcpServer {
   // 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 remains 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;
   };
 
   // Result of <code>create</code> call.
   dictionary CreateInfo {
-    // The ID of the newly created server socket.
+    // The ID of the newly created server 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>listen</code> method.
   // |result| : The result code returned from the underlying network call.
   // A negative value indicates an error.
@@ skipping 142 matching lines @@
 
     // Event raised when a network error occured while the runtime was waiting
     // for new connections on the socket address and port. Once this event is
     // raised, the socket is set to <code>paused</code> and no more
     // <code>onAccept</code> events are raised for this socket until the socket
     // is resumed.
     // |info| : The event data.
     static void onAcceptError(AcceptErrorInfo info);
   };
 };