API docs pretty much done

docs/api.json

@@ -3,13 +3,13 @@
     "name": "Peer",
     "type": "constructor",
     "snippet": "var peer = new Peer([id], [options]);",
-    "description": "A Peer can connect to other peers and listen for connections.",
+    "description": "A peer can connect to other peers and listen for connections.",
     "children": [
       {
         "name": "id",
         "optional": true,
         "type": "string",
-        "description": "Other peers can connect to this peer using the provided ID. If no ID is given, one will be generated by the brokering server.<div class='tip'>It's not recommended that you use this ID to identify peers, as it's meant to be used for brokering connections only. You're recommended to set the metadata option to send other identifying information.</div>"
+        "description": "Other peers can connect to this peer using the provided ID. If no ID is given, one will be generated by the brokering server.<span class='tip'>It's not recommended that you use this ID to identify peers, as it's meant to be used for brokering connections only. You're recommended to set the <a href='#peerconnect-options'><code>metadata</code></a> option to send other identifying information.</span>"
       },
       {
         "name": "options",
@@ -31,6 +31,12 @@
             "type": "number",
             "description": "Server port. Defaults to <code>80</code>."
           },
+          {
+            "name": "secure",
+            "type": "boolean",
+            "tags": ["beta (0.3.0)"],
+            "description": "<code>true</code> if you're using SSL.<span class='tip'>Note that our cloud-hosted server and assets may not support SSL.</span>"
+          },
           {
             "name": "config",
             "type": "object",
@@ -39,6 +45,7 @@
           {
             "name": "debug",
             "type": "number",
+            "tags": ["beta (0.3.0)"],
             "description": "Prints log messages depending on the debug level passed in. Defaults to <code>0</code>.",
             "children": [
               {
@@ -67,13 +74,286 @@
   {
     "name": "peer.connect",
     "type": "method",
-    "snippet": "var connection = peer.connect(id, [options]);",
-    "description": "Does something",
+    "snippet": "var <a href='#dataconnection'>dataConnection</a> = peer.connect(id, [options]);",
+    "description": "Connects to the remote peer specified by <code>id</code> and returns a data connection. Be sure to listen on the <a href='#peeron-error'><code>error</code></a> event in case the connection fails.",
     "children": [
       {
         "name": "id",
         "type": "string",
+        "description": "The brokering ID of the remote peer (their <a href='#peerid'><code>peer.id</code></a>)."
+      },
+      {
+        "name": "options",
+        "optional": true,
+        "type": "object",
+        "children": [
+          {
+            "name": "label",
+            "type": "string",
+            "description": "A unique label by which you want to identify this data connection. If left unspecified, a label will be generated at random. Can be accessed with <a href='#dataconnection-label'><code>dataConnection.label</code></a>."
+          },
+          {
+            "name": "metadata",
+            "description": "Metadata associated with the connection, passed in by whoever initiated the connection. Can be accessed with <a href='#dataconnection-metadata'><code>dataConnection.metadata</code></a>. Can be any serializable type."
+          },
+          {
+            "name": "serialization",
+            "type": "string",
+            "description": "Can be <code>binary</code> (default), <code>binary-utf8</code>, <code>json</code>, or <code>none</code>. Can be accessed with <a href='#dataconnection-serialization'><code>dataConnection.serialization</code></a>.<span class='tip'><code>binary-utf8</code> will take a performance hit because of the way UTF8 strings are packed into binary format.</span>"
+          },
+          {
+            "name": "reliable",
+            "type": "boolean",
+            "description": "[TODO: document this]."
+          }
+        ]
+      }
+    ]
+  },
+
+  {
+    "name": "peer.call",
+    "tags": ["beta (0.3.0)"],
+    "type": "method",
+    "snippet": "var <a href='#mediaconnection'>mediaConnection</a> = peer.call(id, stream, [options]);",
+    "description": "Calls the remote peer specified by <code>id</code> and returns a media connection. Be sure to listen on the <a href='#peeron-error'><code>error</code></a> event in case the connection fails.",
+    "children": [
+      {
+        "name": "id",
+        "type": "string",
+        "description": "The brokering ID of the remote peer (their <a href='#peerid'><code>peer.id</code></a>)."
+      },
+      {
+        "name": "stream",
+        "type": "MediaStream",
         "description": "Something else"
+      },
+      {
+        "name": "options",
+        "type": "object",
+        "optional": true,
+        "children": {
+          "name": "constraints",
+          "type": "object",
+          "description": "[TODO: fill this in.]"
+        }
+      }
+    ]
+  },
+
+  {
+    "name": "peer.on",
+    "type": "method",
+    "snippet": "peer.on(event, callback);",
+    "description": "Set listeners for peer events.",
+    "children": [
+      {
+        "name": "'open'",
+        "type": "event",
+        "snippet": "peer.on('open', function(id) { ... });",
+        "description": "Emitted when a connection to the PeerServer is established. You may use the peer before this is emitted, but messages to the server will be queued. <code>id</code> is the brokering ID of the peer (which was either provided in the constructor or assigned by the server).<span class='tip'>You should not wait for this event before connecting to other peers if connection speed is important.</span>"
+      },
+      {
+        "name": "'connection'",
+        "type": "event",
+        "snippet": "peer.on('connection', function(<a href='#dataconnection'>dataConnection</a>) { ... });",
+        "description": "Emitted when a new data connection is established from a remote peer."
+      },
+      {
+        "name": "'call'",
+        "type": "event",
+        "tags": ["beta (0.3.0)"],
+        "snippet": "peer.on('call', function(<a href='#mediaconnection'>mediaConnection</a>) { ... });",
+        "description": "Emitted when a remote peer attempts to call you. The emitted <code>mediaConnection</code> is not yet active; you must first answer the call (<a href='#mediaconnection-answer'><code>mediaConnection.answer([stream]);</code></a>). Then, you can listen for the <a href='#mediaconnection-on'><code>stream</code></a> event."
+      },
+      {
+        "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>"
+      },
+      {
+        "name": "'error'",
+        "type": "event",
+        "snippet": "peer.on('error', function(err) { ... });",
+        "description": "Errors on the peer are <strong>almost always fatal</strong> and will destroy the peer. Errors from the underlying socket and PeerConnections are forwarded here.<br><br>These come in the following <code>err.type</code> flavors:",
+        "children": [
+          {
+            "name": "'browser-incompatible'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "The client's browser does not support some or all WebRTC features that you are trying to use."
+          },
+          {
+            "name": "'invalid-id'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "The ID passed into the Peer constructor contains illegal characters."
+          },
+          {
+            "name": "'invalid-key'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "The API key passed into the Peer constructor contains illegal characters or is not in the system (cloud server only)."
+          },
+          {
+            "name": "'unavailable-id'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "The ID passed into the Peer constructor is already taken."
+          },
+          {
+            "name": "'ssl-unavailable'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "PeerJS is being used securely, but the cloud server does not support SSL. Use a custom PeerServer."
+          },
+          {
+            "name": "'server-disconnected'",
+            "type": "Error",
+            "description": "You've already disconnected this peer and can no longer make any new connections on it."
+          },
+          {
+            "name": "'server-error'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "Unable to reach the server."
+          },
+          {
+            "name": "'socket-error'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "An error from the underlying socket."
+          },
+          {
+            "name": "'socket-closed'",
+            "type": "Error",
+            "tags": ["fatal"],
+            "description": "The underlying socket closed unexpectedly."
+          }
+        ]
+      }
+    ]
+  },
+
+  {
+    "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='tip'>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.destroy",
+    "type": "method",
+    "snippet": "peer.destroy();",
+    "description": "Close the connection to the server and terminate all existing connections. <a href='#peerdestroyed'><code>peer.destroyed</code></a> will be set to <code>true</code>.<span class='tip'>This cannot be undone; the respective peer object will no longer be able to create or receive any connections, its ID will be forfeited on the (cloud) server, and all of its data and media connections will be closed.</span>"
+  },
+
+  {
+    "name": "peer.id",
+    "type": "string",
+    "description": "The brokering ID of this peer. If no ID was specified in <a href='#peer'>the constructor</a>, this will be <code>undefined</code> until the <a href='#peeron-open'><code>open</code></a> event is emitted."
+  },
+
+  {
+    "name": "peer.connections",
+    "type": "object",
+    "description": "A hash of all connections associated with this peer, keyed by the remote peer's ID.<span class='tip'>We recommend keeping track of connections yourself rather than relying on this hash.</span>"
+  },
+
+  {
+    "name": "peer.disconnected",
+    "type": "boolean",
+    "description": "<code>false</code> if there is an active connection to the PeerServer."
+  },
+
+  {
+    "name": "peer.destroyed",
+    "type": "boolean",
+    "description": "<code>true</code> if this peer and all of its connections can no longer be used."
+  },
+
+  {
+    "name": "DataConnection",
+    "type": "class",
+    "description": "Wraps WebRTC's DataChannel. To get one, use <a href='#peerconnect'><code>peer.connect</code></a> or listen for the <a href='#peeron-connect'><code>connect</code></a> event.<span class='tip'>Because Chrome currently does not support reliable messaging, PeerJS uses the <a href='https://github.com/michellebu/reliable'>Reliable shim</a>. A caveat is that you will no longer be able to customize the serialization format used for data transfer.</span>",
+    "children": [
+      {
+        "name": ".send",
+        "type": "method",
+        "snippet": "dataConnection.send(data);",
+        "description": "<code>data</code> is serialized by BinaryPack by default and sent to the remote peer.",
+        "children": {
+          "name": "data",
+          "description": "You can send any type of data, including objects, strings, and blobs."
+        }
+      },
+      {
+        "name": ".close",
+        "type": "method",
+        "snippet": "dataConnection.close();",
+        "description": "Closes the data connection gracefully, cleaning up underlying DataChannels and PeerConnections."
+      },
+      {
+        "name": ".on",
+        "type": "method",
+        "snippet": "dataConnection.on(event, callback);",
+        "description": "Set listeners for data connection events.",
+        "children": [
+          {
+            "name": "'data'",
+            "type": "event",
+            "snippet": "dataConnection.on('data', function(data) { ... });",
+            "description": "Emitted when data is received from the remote peer."
+          },
+          {
+            "name": "'open'",
+            "type": "event",
+            "snippet": "dataConnection.on('data', function() { ... });",
+            "description": "Emitted when the connection is established and ready-to-use."
+          },
+          {
+            "name": "'close'",
+            "type": "event",
+            "snippet": "dataConnection.on('close', function() { ... });",
+            "description": "Emitted when either you or the remote peer closes the data connection."
+          },
+          {
+            "name": "'error'",
+            "type": "event",
+            "snippet": "dataConnection.on('error', function(err) { ... });"
+          }
+        ]
+      },
+      {
+        "name": ".label",
+        "type": "string",
+        "description": "The optional label passed in or assigned by PeerJS when the connection was initiated."
+      },
+      {
+        "name": ".metadata",
+        "description": "Any type of metadata associated with the connection, passed in by whoever initiated the connection."
+      },
+      {
+        "name": ".serialization",
+        "type": "string",
+        "description": "The serialization format of the data sent over the connection. Can be <code>binary</code> (default), <code>binary-utf8</code>, <code>json</code>, or <code>none</code>."
+      },
+      {
+        "name": ".open",
+        "type": "boolean",
+        "description": "This is true if the connection is open and ready for read/write."
+      },
+      {
+        "name": ".peer",
+        "type": "string",
+        "description": "The ID of the peer on the other end of this connection."
+      },
+      {
+        "name": ".type",
+        "type": "string",
+        "description": "For data connections, this is always <code>'data'</code>."
       }
     ]
   },
@@ -81,29 +361,29 @@
   {
     "name": "MediaConnection",
     "type": "class",
-    "tags": ["beta"],
-    "description": "Wraps WebRTC's media streams. To get one, use <a href='#peercall'><code>peer.call</code></a>.",
+    "tags": ["beta (0.3.0)"],
+    "description": "Wraps WebRTC's media streams. To get one, use <a href='#peercall'><code>peer.call</code></a> or listen for the <a href='#peeron-call'><code>call</code></a> event.",
     "children": [
       {
-        "name": "#answer",
+        "name": ".answer",
         "type": "method",
         "snippet": "mediaConnection.answer([stream]);",
-        "description": "When recieving a <a href='#peeron-call'><code>call</code></a> event on a Peer, you can call <code>answer</code> on the media connection provided by the callback to accept the call and optionally send your own media stream.",
+        "description": "When recieving a <a href='#peeron-call'><code>call</code></a> event on a peer, you can call <code>.answer</code> on the media connection provided by the callback to accept the call and optionally send your own media stream.",
         "children": {
           "name": "stream",
           "optional": true,
           "type": "MediaStream",
-          "description": "A WebRTC media stream from <code>getUserMedia</code>."
+          "description": "A WebRTC media stream from <a href='https://developer.mozilla.org/en-US/docs/Web/API/Navigator.getUserMedia'><code>getUserMedia</code></a>."
         }
       },
       {
-        "name": "#close",
+        "name": ".close",
         "type": "method",
         "snippet": "mediaConnection.close();",
         "description": "Closes the media connection."
       },
       {
-        "name": "#on",
+        "name": ".on",
         "type": "method",
         "snippet": "mediaConnection.on(event, callback);",
         "description": "Set listeners for media connection events.",
@@ -112,25 +392,78 @@
             "name": "'stream'",
             "type": "event",
             "snippet": "mediaConnection.on('stream', function(stream) { ... });",
-            "description": "Fired when the remote peer answers your call. <code>stream</code> is the media stream the remote peer added."
+            "description": "Emitted when a remote peer adds a <code>stream</code>."
+          },
+          {
+            "name": "'close'",
+            "type": "event",
+            "snippet": "mediaConnection.on('close', function() { ... });",
+            "description": "Emitted when either you or the remote peer closes the media connection."
+          },
+          {
+            "name": "'error'",
+            "type": "event",
+            "snippet": "mediaConnection.on('error', function(err) { ... });"
           }
         ]
       },
       {
-        "name": "#metadata",
-        "type": "object",
-        "description": "Metadata associated with the connection, passed in by whoever initiated the connection."
+        "name": ".metadata",
+        "description": "Any type of metadata associated with the connection, passed in by whoever initiated the connection."
       },
       {
-        "name": "#peer",
+        "name": ".peer",
         "type": "string",
-        "description": "The ID of the Peer on the other end of this connection."
+        "description": "The ID of the peer on the other end of this connection."
       },
       {
-        "name": "#type",
+        "name": ".type",
         "type": "string",
         "description": "For media connections, this is always <code>'media'</code>."
       }
     ]
+  },
+
+  {
+    "name": "util",
+    "type": "object",
+    "tags": ["utility"],
+    "description": "Provides a variety of helpful utilities.<span class='tip'>Only the utilities documented here are guaranteed to be present on <code>util</code>. Undocumented utilities can be removed without warning. We don't consider these to be 'breaking changes.'</span>",
+    "children": [
+      {
+        "name": ".browser",
+        "type": "string",
+        "snippet": "if (util.browser === 'Firefox') { /* OK to peer with Firefox peers. */ }",
+        "description": "The current browser. This property can be useful in determining whether or not two peers can connect. For example, as of now data connections are not yet interoperable between major browsers. <code>util.browser</code> can currently have the values 'Firefox', 'Chrome', 'Unsupported', or 'Supported' (unknown WebRTC-compatible browser)."
+      },
+      {
+        "name": ".supports",
+        "type": "object",
+        "snippet": "if (util.supports.data) { /* OK to start a data connection. */ }",
+        "description": "A hash of WebRTC features mapped to booleans that correspond to whether the feature is supported by the current browser.<span class='tip'>Only the properties documented here are guaranteed to be present on <code>util.supports</code>.</span>",
+        "children": [
+          {
+            "name": ".audioVideo",
+            "type": "boolean",
+            "description": "True if the current browser supports media streams and PeerConnection."
+          },
+          {
+            "name": ".data",
+            "type": "boolean",
+            "description": "True if the current browser supports DataChannel and PeerConnection."
+          },
+          {
+            "name": ".binary",
+            "type": "boolean",
+            "description": "True if the current browser supports binary DataChannels."
+          },
+          {
+            "name": ".reliable",
+            "type": "boolean",
+            "description": "True if the current browser supports reliable DataChannels."
+          }
+        ]
+      }
+    ]
   }
 ]

docs/build.js

@@ -5,4 +5,4 @@ var reference = require('reference');
 var file = fs.readFileSync('./api.json');
 
 var template = handlebars.compile(fs.readFileSync('./template.html', {encoding: 'utf8'}));
-fs.writeFile('./index.html', template({html: reference(file)}));
+fs.writeFile('./index.html', template({html: reference(file, {anchor: true})}));

docs/style.css

@@ -1,8 +1,18 @@
 body, html {
   font-size: 14px;
+  line-height: 22px;
   font-family: "Lato", Helvetica, sans-serif;
   color: #454545;
-  text-shadow: 0px -1px 0 rgba(255,255,255,0.6);
+}
+
+.api h2 {
+  color: #E2A62E;
+  letter-spacing: 1px;
+  text-transform: uppercase;
+  font-size: 15px;
+  margin: 0 0 10px 0;
+  padding: 5px 20px;
+  background-color: #50484e;
 }
 
 .api, .start {
@@ -11,43 +21,50 @@ body, html {
   bottom: 0px;
   overflow: scroll;
   box-sizing: border-box;
-  padding: 20px;
+  -moz-box-sizing: border-box;
 }
 
 .start {
+  width: 55%;
   right: 0px;
-  width: 60%;
-  background-color: #fff;
+  background-color: #f9f9f9;
+  text-shadow: 0px -1px 0 rgba(255,255,255,0.6);
 }
 
 .api {
+  color: #f5eff3;
+  font-weight: 300;
   left: 0px;
-  width: 40%;
-  border-right: 1px solid #ccc;
-  background-color: #f5f5f5;
+  width: 45%;
+  border-right: 4px solid #50484e;
+  background-color: #5a5157;
+  text-shadow: 0px -1px 0 #474045;
 }
 
 .child {
-  padding: 5px 0 5px 15px;
+  padding: 5px 0 5px 12px;
 }
 
 .bracket {
-  color: #ccc;
+  font-weight: 800;
+  display: inline-block;
+  margin: 0 2px;
+  color: rgba(255,255,255,0.2);
 }
 
 .toplevel {
-  padding-top: 12px;
+  padding: 10px 20px;
 }
 
 .toplevel > .children > .child {
-  padding-right: 15px;
+  padding-right: 5px;
 }
 
 .children {
-  border-left: 1px dashed #ccc;
+  border-left: 1px dashed rgba(255,255,255,0.2);
 }
 
-.beta .children {
+.beta_030 .children {
   border-left: 1px dashed #E96151;
 }
 
@@ -56,7 +73,7 @@ body, html {
 }
 
 .child:hover {
-  background-color: #fff;
+  background-color: #635960;
 }
 
 /** Label stylings */
@@ -64,15 +81,16 @@ body, html {
   display: inline-block;
   background-color: #454545;
   border-radius: 2px;
-  color: #fff;
+  color: rgba(255,255,255,0.8);
   line-height: 11px;
   padding: 1px 2px;
   margin-left: 5px;
   font-size: 9px;
   letter-spacing: 1px;
   font-weight: 600;
+  font-family: "Lato", Helvetica, sans-serif;
   text-transform: uppercase;
-  border: 1px solid rgba(0,0,0,0.2);
+  border: 1px solid rgba(0,0,0,0.4);
   text-shadow: 0px -1px 0px rgba(0,0,0,0.2);
 }
 
@@ -80,22 +98,35 @@ body, html {
   background-color: #757E2B;
 }
 
-.tag.beta {
+.tag.beta_030 {
   background-color: #E96151;
 }
 
-.tag.method {
+.tag.method, .tag.function {
   background-color: #E2A62E;
 }
 
-.tag.class, .tag.constructor {
-  background-color: #454545;
+.tag.class, .tag.constructor, .tag.utility {
+  background-color: #468F81;
+}
+
+.tag.error {
+  background-color: #8F4537;
 }
 
 .tag.event {
   background-color: #1295D8;
 }
 
+.api a {
+  color: #1295D8;
+  transition: color 200ms;
+}
+
+.api a:hover {
+  color: #33a2dc;
+}
+
 .toplevel > .name {
   font-size: 20px;
 }
@@ -103,31 +134,53 @@ body, html {
 /** /Label stylings */
 
 .api .snippet {
-  font: 12px Courier;
+  color: #a2949d;
+  border-left: 1px solid #40393e;
+  border-top: 1px solid #40393e;
+  border-right: 1px solid #6b666a;
+  border-bottom: 1px solid #6b666a;
+  text-shadow: 0 -1px 0 #393438;
+  font-size: 12px;
+  font-family: Consolas, Inconsolata, 'Bitstream Vera Sans Mono', Menlo, Monaco, 'Andale Mono', 'Courier New', monospace;
+  font-weight: 400;
   display: inline-block;
-  background-color: #fff;
-  padding: 5px 10px;
-  margin: 5px 0 0 5px;
+  background-color: #474045;
+  padding: 3px 8px;
+  margin: 5px 0 0 10px;
 }
 
+/* We want to be able to use the names as an anchor. */
 .api .name {
   font-weight: 600;
   display: inline-block;
   margin-bottom: 5px;
 }
 
-.api .code {
-  font-family: Courier;
+.name a {
+  cursor: pointer;
+  color: #fff;
+  text-decoration: none;
+  transition: color 300ms;
+}
+
+.name a:hover {
+  color: #e7e0e5;
 }
+/* /name */
 
 .tip {
-  background-color: #454545;
-  font-size: 12px;
+  opacity: 0.9;
+  display: block;
+  background-color: #8F4537;
+  font-size: 13px;
+  line-height: 18px;
+  font-weight: 400;
   border-radius: 2px;
-  padding: 8px;
-  color: #fff;
+  padding: 5px 8px;
+  color: #ddaba2;
   border: 1px solid rgba(0,0,0,0.2);
   text-shadow: 0px -1px 0px rgba(0,0,0,0.2);
+  margin: 8px 0 0 0;
 }
 
 #peer-options-debug .child {
@@ -138,3 +191,12 @@ body, html {
   display: inline-block;
   margin-left: 10px;
 }
+
+.api code {
+  font-family: Consolas, Inconsolata, 'Bitstream Vera Sans Mono', Menlo, Monaco, 'Andale Mono', 'Courier New', monospace;
+  border-radius: 2px;
+  border: 1px solid rgba(255,255,255,0.2);
+  background: rgba(255,255,255,0.1);
+  font-size: 12px;
+  padding: 2px;
+,}

docs/template.html

@@ -1,4 +1,5 @@
 <head>
+  <title>PeerJS Documentation</title>
   <link href='http://fonts.googleapis.com/css?family=Lato:300,400,700,900' rel='stylesheet' type='text/css'>
   <link href="./style.css" rel="stylesheet" type="text/css">
 </head>