Add documentation for WebRTC classes.

4 files changed, 171 insertions, 1 deletions

diff --git a/modules/webrtc/config.py b/modules/webrtc/config.py
index 2e3a18ad0e..48b4c33c5d 100644
--- a/modules/webrtc/config.py
+++ b/modules/webrtc/config.py
@@ -7,7 +7,8 @@ def configure(env):
 def get_doc_classes():
     return [
         "WebRTCPeerConnection",
-        "WebRTCDataChannel"
+        "WebRTCDataChannel",
+        "WebRTCMultiplayer"
     ]
 
 def get_doc_path():
diff --git a/modules/webrtc/doc_classes/WebRTCDataChannel.xml b/modules/webrtc/doc_classes/WebRTCDataChannel.xml
index dcc14d4ddb..f03ae864f8 100644
--- a/modules/webrtc/doc_classes/WebRTCDataChannel.xml
+++ b/modules/webrtc/doc_classes/WebRTCDataChannel.xml
@@ -11,85 +11,106 @@
 			<return type="void">
 			</return>
 			<description>
+				Closes this data channel, notifying the other peer.
 			</description>
 		</method>
 		<method name="get_id" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns the id assigned to this channel during creation (or auto-assigned during negotiation).
+				If the channel is not negotiated out-of-band the id will only be available after the connection is established (will return [code]65535[/code] until then).
 			</description>
 		</method>
 		<method name="get_label" qualifiers="const">
 			<return type="String">
 			</return>
 			<description>
+				Returns the label assigned to this channel during creation.
 			</description>
 		</method>
 		<method name="get_max_packet_life_time" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns the maxPacketLifeTime value assigned to this channel during creation.
+				Will be [code]65535[/code] if not specified.
 			</description>
 		</method>
 		<method name="get_max_retransmits" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns the maxRetransmits value assigned to this channel during creation.
+				Will be [code]65535[/code] if not specified.
 			</description>
 		</method>
 		<method name="get_protocol" qualifiers="const">
 			<return type="String">
 			</return>
 			<description>
+				Returns the sub-proctocol assigned to this channel during creation. An empty string if not specified.
 			</description>
 		</method>
 		<method name="get_ready_state" qualifiers="const">
 			<return type="int" enum="WebRTCDataChannel.ChannelState">
 			</return>
 			<description>
+				Returns the current state of this channel, see [enum WebRTCDataChannel.ChannelState].
 			</description>
 		</method>
 		<method name="is_negotiated" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns [code]true[/code] if this channel was created with out-of-band configuration.
 			</description>
 		</method>
 		<method name="is_ordered" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns [code]true[/code] if this channel was created with ordering enabled (default).
 			</description>
 		</method>
 		<method name="poll">
 			<return type="int" enum="Error">
 			</return>
 			<description>
+				Reserved, but not used for now.
 			</description>
 		</method>
 		<method name="was_string_packet" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns [code]true[/code] if the last received packet was transfered as text. See [property write_mode].
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="write_mode" type="int" setter="set_write_mode" getter="get_write_mode" enum="WebRTCDataChannel.WriteMode">
+			The transfer mode to use when sending outgoing packet. Either text or binary.
 		</member>
 	</members>
 	<constants>
 		<constant name="WRITE_MODE_TEXT" value="0" enum="WriteMode">
+			Tells the channel to send data over this channel as text. An external peer (non-godot) would receive this as a string.
 		</constant>
 		<constant name="WRITE_MODE_BINARY" value="1" enum="WriteMode">
+			Tells the channel to send data over this channel as binary. An external peer (non-godot) would receive this as arraybuffer or blob.
 		</constant>
 		<constant name="STATE_CONNECTING" value="0" enum="ChannelState">
+			The channel was created, but it's still trying to connect.
 		</constant>
 		<constant name="STATE_OPEN" value="1" enum="ChannelState">
+			The channel is currently open, and data can flow over it.
 		</constant>
 		<constant name="STATE_CLOSING" value="2" enum="ChannelState">
+			The channel is being closed, no new messages will be accepted, but those already in queue will be flushed.
 		</constant>
 		<constant name="STATE_CLOSED" value="3" enum="ChannelState">
+			The channel was closed, or connection failed.
 		</constant>
 	</constants>
 </class>
diff --git a/modules/webrtc/doc_classes/WebRTCMultiplayer.xml b/modules/webrtc/doc_classes/WebRTCMultiplayer.xml
new file mode 100644
index 0000000000..2b0622fffa
--- /dev/null
+++ b/modules/webrtc/doc_classes/WebRTCMultiplayer.xml
@@ -0,0 +1,85 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="WebRTCMultiplayer" inherits="NetworkedMultiplayerPeer" category="Core" version="3.2">
+	<brief_description>
+		A simple interface to create a peer-to-peer mesh network composed of [WebRTCPeerConnection] that is compatible with the [MultiplayerAPI].
+	</brief_description>
+	<description>
+		This class constructs a full mesh of [WebRTCPeerConnection] (one connection for each peer) that can be used as a [member MultiplayerAPI.network_peer].
+		You can add each [WebRTCPeerConnection] via [method add_peer] or remove them via [method remove_peer]. Peers must be added in [constant WebRTCPeerConnection.STATE_NEW] state to allow it to create the appropriate channels. This class will not create offers nor set descriptions, it will only poll them, and notify connections and disconnections.
+		[signal NetworkedMultiplayerPeer.connection_succeeded] and [signal NetworkedMultiplayerPeer.server_disconnected] will not be emitted unless [code]server_compatibility[/code] is [code]true[/code] in [method initialize]. Beside that data transfer works like in a [NetworkedMultiplayerPeer].
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="add_peer">
+			<return type="int" enum="Error">
+			</return>
+			<argument index="0" name="peer" type="WebRTCPeerConnection">
+			</argument>
+			<argument index="1" name="peer_id" type="int">
+			</argument>
+			<argument index="2" name="unreliable_lifetime" type="int" default="1">
+			</argument>
+			<description>
+				Add a new peer to the mesh with the given [code]peer_id[/code]. The [WebRTCPeerConnection] must be in state [constant WebRTCPeerConnection.STATE_NEW].
+				Three channels will be created for reliable, unreliable, and ordered transport. The value of [code]unreliable_lifetime[/code] will be passed to the [code]maxPacketLifetime[/code] option when creating unreliable and ordered channels (see [method WebRTCPeerConnection.create_data_channel]).
+			</description>
+		</method>
+		<method name="close">
+			<return type="void">
+			</return>
+			<description>
+				Close all the add peer connections and channels, freeing all resources.
+			</description>
+		</method>
+		<method name="get_peer">
+			<return type="Dictionary">
+			</return>
+			<argument index="0" name="peer_id" type="int">
+			</argument>
+			<description>
+				Return a dictionary representation of the peer with given [code]peer_id[/code] with three keys. [code]connection[/code] containing the [WebRTCPeerConnection] to this peer, [code]channels[/code] an array of three [WebRTCDataChannel], and [code]connected[/code] a boolean representing if the peer connection is currently connected (all three channels are open).
+			</description>
+		</method>
+		<method name="get_peers">
+			<return type="Dictionary">
+			</return>
+			<description>
+				Returns a dictionary which keys are the peer ids and values the peer representation as in [method get_peer]
+			</description>
+		</method>
+		<method name="has_peer">
+			<return type="bool">
+			</return>
+			<argument index="0" name="peer_id" type="int">
+			</argument>
+			<description>
+				Returns [code]true[/code] if the given [code]peer_id[/code] is in the peers map (it might not be connected though).
+			</description>
+		</method>
+		<method name="initialize">
+			<return type="int" enum="Error">
+			</return>
+			<argument index="0" name="peer_id" type="int">
+			</argument>
+			<argument index="1" name="server_compatibility" type="bool" default="false">
+			</argument>
+			<description>
+				Initialize the multiplayer peer with the given [code]peer_id[/code] (must be between 1 and 2147483647).
+				If [code]server_compatibilty[/code] is [code]false[/code] (default), the multiplayer peer will be immediately in state [constant NetworkedMultiplayerPeer.CONNECTION_CONNECTED] and [signal NetworkedMultiplayerPeer.connection_succeeded] will not be emitted.
+				If [code]server_compatibilty[/code] is [code]true[/code] the peer will suppress all [signal NetworkedMultiplayerPeer.peer_connected] signals until a peer with id [constant NetworkedMultiplayerPeer.TARGET_PEER_SERVER] connects and then emit [signal NetworkedMultiplayerPeer.connection_succeeded]. After that the signal [signal NetworkedMultiplayerPeer.peer_connected] will be emitted for every already connected peer, and any new peer that might connect. If the server peer disconnects after that, signal [signal NetworkedMultiplayerPeer.server_disconnected] will be emitted and state will become [constant NetworkedMultiplayerPeer.CONNECTION_CONNECTED].
+			</description>
+		</method>
+		<method name="remove_peer">
+			<return type="void">
+			</return>
+			<argument index="0" name="peer_id" type="int">
+			</argument>
+			<description>
+				Remove the peer with given [code]peer_id[/code] from the mesh. If the peer was connected, and [signal NetworkedMultiplayerPeer.peer_connected] was emitted for it, then [signal NetworkedMultiplayerPeer.peer_disconnected] will be emitted.
+			</description>
+		</method>
+	</methods>
+	<constants>
+	</constants>
+</class>
diff --git a/modules/webrtc/doc_classes/WebRTCPeerConnection.xml b/modules/webrtc/doc_classes/WebRTCPeerConnection.xml
index 8b14c60deb..aa2c856b6e 100644
--- a/modules/webrtc/doc_classes/WebRTCPeerConnection.xml
+++ b/modules/webrtc/doc_classes/WebRTCPeerConnection.xml
@@ -1,8 +1,17 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="WebRTCPeerConnection" inherits="Reference" category="Core" version="3.2">
 	<brief_description>
+		Interface to a WebRTC peer connection.
 	</brief_description>
 	<description>
+		A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain and monitor the connection.
+
+		Setting up a WebRTC connection between two peers from now on) may not seem a trival task, but it can be broken down into 3 main steps:
+		- The peer that wants to initiate the connection ([code]A[/code] from now on) creates an offer and send it to the other peer ([code]B[/code] from now on).
+		- [code]B[/code] receives the offer, generate and answer, and sends it to [code]B[/code]).
+		- [code]A[/code] and [code]B[/code] then generates and exchange ICE candiates with each other.
+
+		After these steps, the connection should become connected. Keep on reading or look into the tutorial for more information.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -17,12 +26,14 @@
 			<argument index="2" name="name" type="String">
 			</argument>
 			<description>
+				Add an ice candidate generated by a remote peer (and received over the signaling server). See [signal ice_candidate_created].
 			</description>
 		</method>
 		<method name="close">
 			<return type="void">
 			</return>
 			<description>
+				Close the peer connection and all data channels associated with it. Note, you cannot reuse this object for a new connection unless you call [method initialize].
 			</description>
 		</method>
 		<method name="create_data_channel">
@@ -35,18 +46,38 @@
 }">
 			</argument>
 			<description>
+				Returns a new [WebRTCDataChannel] (or [code]null[/code] on failure) with given [code]label[/code] and optionally configured via the [code]options[/code] dictionary. This method can only be called when the connection is in state [constant STATE_NEW].
+				There are two ways to create a working data channel: either call [method create_data_channel] on only one of the peer and listen to [signal data_channel_received] on the other, or call [method create_data_channel] on both peers, with the same values, and the [code]negotiated[/code] option set to [code]true[/code].
+				Valid [code]options[/code] are:
+				[code]
+				{
+				    "negotiated": true, # When set to true (default off), means the channel is negotiated out of band. "id" must be set too. data_channel_received will not be called.
+				    "id": 1, # When "negotiated" is true this value must also be set to the same value on both peer.
+
+				    # Only one of maxRetransmits and maxPacketLifeTime can be specified, not both. They make the channel unreliable (but also better at real time).
+				    "maxRetransmits": 1, # Specify the maximum number of attempt the peer will make to retransmits packets if they are not acknowledged.
+				    "maxPacketLifeTime": 100, # Specify the maximum amount of time before giving up retransmitions of unacknowledged packets (in milliseconds).
+				    "ordered": true, # When in unreliable mode (i.e. either "maxRetransmits" or "maxPacketLifetime" is set), "ordered" (true by default) specify if packet ordering is to be enforced.
+
+				    "protocol": "my-custom-protocol", # A custom sub-protocol string for this channel.
+				}
+				[/code]
+				NOTE: You must keep a reference to channels created this way, or it will be closed.
 			</description>
 		</method>
 		<method name="create_offer">
 			<return type="int" enum="Error">
 			</return>
 			<description>
+				Creates a new SDP offer to start a WebRTC connection with a remote peer. At least one [WebRTCDataChannel] must have been created before calling this method.
+				If this functions returns [code]OK[/code], [signal session_description_created] will be called when the session is ready to be sent.
 			</description>
 		</method>
 		<method name="get_connection_state" qualifiers="const">
 			<return type="int" enum="WebRTCPeerConnection.ConnectionState">
 			</return>
 			<description>
+				Returns the connection state. See [enum ConnectionState].
 			</description>
 		</method>
 		<method name="initialize">
@@ -57,12 +88,29 @@
 }">
 			</argument>
 			<description>
+				Re-initialize this peer connection, closing any previously active connection, and going back to state [constant STATE_NEW]. A dictionary of [code]options[/code] can be passed to configure the peer connection.
+				Valid [code]options[/code] are:
+				[code]
+				{
+				    "iceServers": [
+				        {
+				            "urls": [ "stun:stun.example.com:3478" ], # One or more STUN servers.
+				        },
+				        {
+				            "urls": [ "turn:turn.example.com:3478" ], # One or more TURN servers.
+				            "username": "a_username", # Optional username for the TURN server.
+				            "credentials": "a_password", # Optional password for the TURN server.
+				        }
+				    ]
+				}
+				[/code]
 			</description>
 		</method>
 		<method name="poll">
 			<return type="int" enum="Error">
 			</return>
 			<description>
+				Call this method frequently (e.g. in [method Node._process] or [method Node._fixed_process]) to properly receive signals.
 			</description>
 		</method>
 		<method name="set_local_description">
@@ -73,6 +121,8 @@
 			<argument index="1" name="sdp" type="String">
 			</argument>
 			<description>
+				Sets the SDP description of the local peer. This should be called in response to [signal session_description_created].
+				If [code]type[/code] is [code]answer[/code] the peer will start emitting [signal ice_candidate_created].
 			</description>
 		</method>
 		<method name="set_remote_description">
@@ -83,6 +133,9 @@
 			<argument index="1" name="sdp" type="String">
 			</argument>
 			<description>
+				Sets the SDP description of the remote peer. This should be called with the values generated by a remote peer and received over the signaling server.
+				If [code]type[/code] is [code]offer[/code] the peer will emit [signal session_description_created] with the appropriate answer.
+				If [code]type[/code] is [code]answer[/code] the peer will start emitting [signal ice_candidate_created].
 			</description>
 		</method>
 	</methods>
@@ -91,6 +144,8 @@
 			<argument index="0" name="channel" type="Object">
 			</argument>
 			<description>
+				Emitted when a new in-band channel is received, i.e. when the channel was created with [code]negotiated: false[/code] (default).
+				The object will be an instance of [WebRTCDataChannel]. You must keep a reference of it or it will be closed automatically. See [method create_data_channel]
 			</description>
 		</signal>
 		<signal name="ice_candidate_created">
@@ -101,6 +156,7 @@
 			<argument index="2" name="name" type="String">
 			</argument>
 			<description>
+				Emitted when a new ICE candidate has been created. The three parameters are meant to be passed to the remote peer over the signaling server.
 			</description>
 		</signal>
 		<signal name="session_description_created">
@@ -109,21 +165,28 @@
 			<argument index="1" name="sdp" type="String">
 			</argument>
 			<description>
+				Emitted after a successful call to [method create_offer] or [method set_remote_description] (when it generates an answer). The parameters are meant to be passed to [method set_local_description] on this object, and sent to the remote peer over the signaling server.
 			</description>
 		</signal>
 	</signals>
 	<constants>
 		<constant name="STATE_NEW" value="0" enum="ConnectionState">
+			The connection is new, data channels and an offer can be created in this state.
 		</constant>
 		<constant name="STATE_CONNECTING" value="1" enum="ConnectionState">
+			The peer is connecting, ICE is in progress, non of the transports has failed.
 		</constant>
 		<constant name="STATE_CONNECTED" value="2" enum="ConnectionState">
+			The peer is connected, all ICE transports are connected.
 		</constant>
 		<constant name="STATE_DISCONNECTED" value="3" enum="ConnectionState">
+			At least one ICE transport is disconnected.
 		</constant>
 		<constant name="STATE_FAILED" value="4" enum="ConnectionState">
+			One or more of the ICE transports failed.
 		</constant>
 		<constant name="STATE_CLOSED" value="5" enum="ConnectionState">
+			The peer connection is closed (after calling [method close] for example).
 		</constant>
 	</constants>
 </class>