From e4096b5157f53a04cb18d640c87faae706cd64f0 Mon Sep 17 00:00:00 2001
From: Maksym Khomenko <maksym.khomenko@skelia.partners>
Date: Thu, 28 Sep 2023 18:19:50 +0300
Subject: [PATCH] webrtcsink: README: add documentation for custom signaller

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs/-/merge_requests/1340>
---
 net/webrtc/README.md                          |  4 ++--
 net/webrtc/examples/README.md                 |  7 +++++-
 .../webrtcsink-custom-signaller/README.md     | 23 +++++++++++++++++++
 3 files changed, 31 insertions(+), 3 deletions(-)
 create mode 100644 net/webrtc/examples/webrtcsink-custom-signaller/README.md

diff --git a/net/webrtc/README.md b/net/webrtc/README.md
index f10806ef..97c5e597 100644
--- a/net/webrtc/README.md
+++ b/net/webrtc/README.md
@@ -28,10 +28,10 @@ set of streams to any number of consumers, `webrtcsink` (which wraps
 * Application-provided signalling: `webrtcsink` can be instantiated by an
   application with a custom signaller. That signaller must be a GObject, and
   must implement the `Signallable` interface as defined
-  [here](src/webrtcsink/mod.rs). The [default signaller](src/signaller/mod.rs)
+  [here](src/signaller/mod.rs). The [default signaller](src/signaller/imp.rs)
   can be used as an example.
 
-  An [example project] is also available to use as a boilerplate for
+  An [example](examples/webrtcsink-custom-signaller/README.md) is also available to use as a boilerplate for
   implementing and using a custom signaller.
 
 * Sandboxed consumers: when a consumer is added, its encoder / payloader /
diff --git a/net/webrtc/examples/README.md b/net/webrtc/examples/README.md
index 7b402e69..a2a9ce9e 100644
--- a/net/webrtc/examples/README.md
+++ b/net/webrtc/examples/README.md
@@ -1,6 +1,6 @@
 # webrtcsink examples
 
-Collection (1-sized for now) of webrtcsink examples
+Collection of webrtcsink examples
 
 ## webrtcsink-stats-server
 
@@ -16,3 +16,8 @@ cargo run --example webrtcsink-stats-server
 
 Once it is running, follow the instruction in the webrtcsink-stats folder to
 run an example client.
+
+## webrtcsink-custom-signaller
+
+An example of custom signaller implementation, see the corresponding
+[README](webrtcsink-custom-signaller/README.md) for more details on code and usage. 
diff --git a/net/webrtc/examples/webrtcsink-custom-signaller/README.md b/net/webrtc/examples/webrtcsink-custom-signaller/README.md
new file mode 100644
index 00000000..f47fee27
--- /dev/null
+++ b/net/webrtc/examples/webrtcsink-custom-signaller/README.md
@@ -0,0 +1,23 @@
+# WebRTCSink custom signaller
+
+A simple application that consist of two parts:
+
+* main executable, which demonstrates how to instantiate WebRTCSink with a custom signaller
+* `signaller` module, which provides all the required boilerplate code
+  and stub implementations needed to create a custom signaller
+
+Run with:
+
+``` shell
+cargo run --example webrtcsink-custom-signaller
+```
+
+The expected output is a not-implemented panic (from `imp::Signaller::start` function):
+
+```text
+thread 'tokio-runtime-worker' panicked at 'not implemented', net/webrtc/examples/webrtcsink-custom-signaller/signaller/imp.rs:14:9
+note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+```
+
+Simply implement the methods in [imp.rs](signaller/imp.rs) and you should be good
+to go!