docs: document `MediaConnection` inline

docs/api.json

@@ -421,88 +421,5 @@
         "description": "The number of messages queued to be sent once the browser buffer is no longer full."
       }
     ]
-  },
-  {
-    "name": "MediaConnection",
-    "type": "class",
-    "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",
-        "type": "method",
-        "snippet": "mediaConnection.answer([stream],[options]);",
-        "description": "When receiving 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 <a href='https://developer.mozilla.org/en-US/docs/Web/API/Navigator.getUserMedia'><code>getUserMedia</code></a>."
-          },
-          {
-            "name": "options",
-            "optional": true,
-            "type": "object",
-            "children": [
-              {
-                "name": "sdpTransform",
-                "type": "method",
-                "description": "Function which runs before create answer to modify sdp answer message."
-              }
-            ]
-          }
-        ]
-      },
-      {
-        "name": ".close",
-        "type": "method",
-        "snippet": "mediaConnection.close();",
-        "description": "Closes the media connection."
-      },
-      {
-        "name": ".on",
-        "type": "method",
-        "snippet": "mediaConnection.on(event, callback);",
-        "description": "Set listeners for media connection events.",
-        "children": [
-          {
-            "name": "'stream'",
-            "type": "event",
-            "snippet": "mediaConnection.on('stream', function(stream) { ... });",
-            "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. <span class='warn'>Firefox does not yet support this event.</span>"
-          },
-          {
-            "name": "'error'",
-            "type": "event",
-            "snippet": "mediaConnection.on('error', function(err) { ... });"
-          }
-        ]
-      },
-      {
-        "name": ".open",
-        "type": "boolean",
-        "description": "Whether the media connection is active (e.g. your call has been answered). You can check this if you want to set a maximum wait time for a one-sided call."
-      },
-      {
-        "name": ".metadata",
-        "description": "Any type of metadata associated with the connection, passed in by whoever initiated the connection."
-      },
-      {
-        "name": ".peer",
-        "type": "string",
-        "description": "The ID of the peer on the other end of this connection."
-      },
-      {
-        "name": ".type",
-        "type": "string",
-        "description": "For media connections, this is always <code>'media'</code>."
-      }
-    ]
   }
 ]

lib/baseconnection.ts

@@ -6,8 +6,17 @@ import { ConnectionType } from "./enums";
 export type BaseConnectionEvents = {
 	/**
 	 * Emitted when either you or the remote peer closes the connection.
+	 *
+	 * ```ts
+	 * connection.on('close', () => { ... });
+	 * ```
 	 */
 	close: () => void;
+	/**
+	 * ```ts
+	 * connection.on('error', (error) => { ... });
+	 * ```
+	 */
 	error: (error: Error) => void;
 	iceStateChanged: (state: RTCIceConnectionState) => void;
 };
@@ -17,6 +26,10 @@ export abstract class BaseConnection<
 > extends EventEmitter<T & BaseConnectionEvents> {
 	protected _open = false;
 
+	/**
+	 * Any type of metadata associated with the connection,
+	 * passed in by whoever initiated the connection.
+	 */
 	readonly metadata: any;
 	connectionId: string;
 
@@ -24,11 +37,18 @@ export abstract class BaseConnection<
 
 	abstract get type(): ConnectionType;
 
+	/**
+	 * Whether the media connection is active (e.g. your call has been answered).
+	 * You can check this if you want to set a maximum wait time for a one-sided call.
+	 */
 	get open() {
 		return this._open;
 	}
 
 	constructor(
+		/**
+		 * The ID of the peer on the other end of this connection.
+		 */
 		readonly peer: string,
 		public provider: Peer,
 		readonly options: any,

lib/exports.ts

@@ -1,5 +1,6 @@
 export { util, type Util } from "./util";
 import { Peer } from "./peer";
+export type { PeerEvents } from "./peer";
 
 export type {
 	PeerJSOption,
@@ -9,7 +10,7 @@ export type {
 } from "./optionInterfaces";
 export type { UtilSupportsObj } from "./util";
 export type { DataConnection } from "./dataconnection";
-export type { MediaConnection } from "./mediaconnection";
+export type { MediaConnection, MediaConnectionEvents } from "./mediaconnection";
 export type { LogLevel } from "./logger";
 export type {
 	ConnectionType,

lib/mediaconnection.ts

@@ -7,15 +7,20 @@ import { BaseConnection } from "./baseconnection";
 import { ServerMessage } from "./servermessage";
 import type { AnswerOption } from "./optionInterfaces";
 
-type MediaConnectionEvents = {
+export type MediaConnectionEvents = {
 	/**
 	 * Emitted when a connection to the PeerServer is established.
+	 *
+	 * ```ts
+	 * mediaConnection.on('stream', (stream) => { ... });
+	 * ```
 	 */
 	stream: (stream: MediaStream) => void;
 };
 
 /**
- * Wraps the streaming interface between two Peers.
+ * Wraps WebRTC's media streams.
+ * To get one, use {@apilink Peer.call} or listen for the {@apilink PeerEvents | `call`} event.
  */
 export class MediaConnection extends BaseConnection<MediaConnectionEvents> {
 	private static readonly ID_PREFIX = "mc_";
@@ -24,6 +29,9 @@ export class MediaConnection extends BaseConnection<MediaConnectionEvents> {
 	private _localStream: MediaStream;
 	private _remoteStream: MediaStream;
 
+	/**
+	 * For media connections, this is always 'media'.
+	 */
 	get type() {
 		return ConnectionType.Media;
 	}
@@ -79,6 +87,16 @@ export class MediaConnection extends BaseConnection<MediaConnectionEvents> {
 		}
 	}
 
+	/**
+	 * When receiving a {@apilink PeerEvents | `call`} event on a peer, you can call
+	 * `answer` on the media connection provided by the callback to accept the call
+	 * and optionally send your own media stream.
+
+	 *
+	 * @param stream A WebRTC media stream.
+	 * @param options
+	 * @returns
+	 */
 	answer(stream?: MediaStream, options: AnswerOption = {}): void {
 		if (this._localStream) {
 			logger.warn(
@@ -111,7 +129,9 @@ export class MediaConnection extends BaseConnection<MediaConnectionEvents> {
 	 * Exposed functionality for users.
 	 */
 
-	/** Allows user to close connection. */
+	/**
+	 * Closes the media connection.
+	 */
 	close(): void {
 		if (this._negotiator) {
 			this._negotiator.cleanup();

lib/optionInterfaces.ts

@@ -1,4 +1,7 @@
 export interface AnswerOption {
+	/**
+	 * Function which runs before create answer to modify sdp answer message.
+	 */
 	sdpTransform?: Function;
 }
 

lib/peer.ts

@@ -32,7 +32,7 @@ class PeerOptions implements PeerJSOption {
 	logFunction?: (logLevel: LogLevel, ...rest: any[]) => void;
 }
 
-type PeerEvents = {
+export type PeerEvents = {
 	/**
 	 * Emitted when a connection to the PeerServer is established.
 	 */