Update docs

docs/api.json

@@ -176,7 +176,13 @@
         "name": "'close'",
         "type": "event",
         "snippet": "peer.on('close', function() { ... });",
-        "description": "Emitted when the peer is <a href='#peerdestroy'>destroyed</a>.<span class='tip'>To be extra certain that peers clean up correctly, we recommend calling <code>peer.destroy()</code> on a peer when it is no longer needed.</span>"
+        "description": "Emitted when the peer is <a href='#peerdestroy'>destroyed</a> and can no longer accept or create any new connections. At this time, the peer's connections will all be closed. <span class='tip'>To be extra certain that peers clean up correctly, we recommend calling <code>peer.destroy()</code> on a peer when it is no longer needed.</span>"
+      },
+      {
+        "name": "'disconnected'",
+        "type": "event",
+        "snippet": "peer.on('disconnected', function() { ... });",
+        "description": "Emitted when the peer is disconnected from the signalling server, either <a href='#peerdisconnect'>manually</a> or because the connection to the signalling server was lost. When a peer is disconnected, its existing connections will stay alive, but the peer cannot accept or create any new connections. You can reconnect to the server by calling <a href='#peerreconnect'><code>peer.reconnect()</code></a>."
       },
       {
         "name": "'error'",
@@ -190,6 +196,11 @@
             "tags": ["fatal"],
             "description": "The client's browser does not support some or all WebRTC features that you are trying to use."
           },
+          {
+            "name": "'disconnected'",
+            "type": "Error",
+            "description": "You've already disconnected this peer from the server and can no longer make any new connections on it."
+          },
           {
             "name": "'invalid-id'",
             "type": "Error",
@@ -203,21 +214,20 @@
             "description": "The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only)."
           },
           {
-            "name": "'unavailable-id'",
+            "name": "'network'",
             "type": "Error",
-            "tags": ["fatal"],
-            "description": "The ID passed into the Peer constructor is already taken."
+            "description": "Lost or cannot establish a connection to the signalling server."
           },
           {
-            "name": "'ssl-unavailable'",
+            "name": "'peer-unavailable'",
             "type": "Error",
-            "tags": ["fatal"],
-            "description": "PeerJS is being used securely, but the cloud server does not support SSL. Use a custom PeerServer."
+            "description": "The peer you're trying to connect to does not exist."
           },
           {
-            "name": "'server-disconnected'",
+            "name": "'ssl-unavailable'",
             "type": "Error",
-            "description": "You've already disconnected this peer and can no longer make any new connections on it."
+            "tags": ["fatal"],
+            "description": "PeerJS is being used securely, but the cloud server does not support SSL. Use a custom PeerServer."
           },
           {
             "name": "'server-error'",
@@ -236,6 +246,17 @@
             "type": "Error",
             "tags": ["fatal"],
             "description": "The underlying socket closed unexpectedly."
+          },
+          {
+            "name": "'unavailable-id'",
+            "type": "Error",
+            "tags": ["sometimes fatal"],
+            "description": "The ID passed into the Peer constructor is already taken.<span class='warn'>This error is not fatal if your peer has open peer-to-peer connections. This can happen if you attempt to <a href='#peerreconnect'>reconnect</a> a peer that has been <a href='#peerdisconnect'>disconnected from the server</a>, but its old ID has now been taken.</span>"
+          },
+          {
+            "name": "'webrtc'",
+            "type": "Error",
+            "description": "Native WebRTC errors."
           }
         ]
       }
@@ -246,9 +267,17 @@
     "name": "peer.disconnect",
     "type": "method",
     "snippet": "peer.disconnect();",
-    "description": "Close the connection to the server, leaving all existing data and media connections intact. <a href='#peerdisconnected'><code>peer.disconnected</code></a> will be set to <code>true</code>.<span class='warn'>This cannot be undone; the respective peer object will no longer be able to create or receive any connections and its ID will be forfeited on the (cloud) server.</span>"
+    "description": "Close the connection to the server, leaving all existing data and media connections intact. <a href='#peerdisconnected'><code>peer.disconnected</code></a> will be set to <code>true</code> and the <a href='#peeron-disconnected'><code>disconnected</code></a> event will fire.<span class='warn'>This cannot be undone; the respective peer object will no longer be able to create or receive any connections and its ID will be forfeited on the (cloud) server.</span>"
+  },
+
+  {
+    "name": "peer.reconnect",
+    "type": "method",
+    "snippet": "peer.reconnect();",
+    "description": "Attempt to reconnect to the server with the peer's old ID. Only <a href='#peerdisconnect'>disconnected peers</a> can be reconnected. Destroyed peers cannot be reconnected. If the connection fails (as an example, if the peer's old ID is now taken), the peer's existing connections will not close, but any associated errors events will fire."
   },
 
+
   {
     "name": "peer.destroy",
     "type": "method",