event: add some more documentation on stream-id

... where it might end up being used for.

diff --git a/gst/gstevent.c b/gst/gstevent.c
index 7eb41d3..e0e0ea6 100644 (file)
--- a/gst/gstevent.c
+++ b/gst/gstevent.c
@@ -1460,7 +1460,10 @@ gst_event_parse_sink_message (GstEvent * event, GstMessage ** msg)
  * stream is split into (potentially) multiple new streams, e.g. in a demuxer,
  * but not for every single element in the pipeline.
  * gst_pad_create_stream_id() or gst_pad_create_stream_id_printf() can be
- * used to create a stream-id.
+ * used to create a stream-id.  There are no particular semantics for the
+ * stream-id, though it should be deterministic (to support stream matching)
+ * and it might be used to order streams (besides any information conveyed by
+ * stream flags).
  *
  * Returns: (transfer full): the new STREAM_START event.
  */