Merge branch 'docs' into 'master'

Add a few gotchas to the documentation

See merge request pipewire/pipewire!2186

src/pipewire/properties.h

@@ -25,12 +25,19 @@ extern "C" {
  * Both keys and values are strings which keeps things simple.
  * Encoding of arbitrary values should be done by using a string
  * serialization such as base64 for binary blobs.
+ *
+ * Despite the fact that \ref struct pw_properties is visible, you
+ * should always create and update instances of it using the
+ * functions in this file, because they need to update additional,
+ * not publicly accessible data for each instance.
  */
 
 /**
  * \addtogroup pw_properties
  * \{
  */
+/* Do not use this struct directly, use pw_properties_... functions
+ * to create, edit and access properties. */
 struct pw_properties {
 	struct spa_dict dict;	/**< dictionary of key/values */
 	uint32_t flags;		/**< extra flags */

src/pipewire/stream.h

@@ -513,7 +513,10 @@ struct pw_stream *
 pw_stream_new_simple(struct pw_loop *loop,	/**< a \ref pw_loop to use as the main loop */
 		     const char *name,		/**< a stream media name */
 		     struct pw_properties *props,/**< stream properties, ownership is taken */
-		     const struct pw_stream_events *events,	/**< stream events */
+		     const struct pw_stream_events *events,	/**< stream events. Does not take ownership,
+						 		  * but stores the original struct pointer.
+							          * Can be modified after creation, but only
+						                  * from the main loop. */
 		     void *data					/**< data passed to events */);
 
 /** Destroy a stream */
@@ -521,7 +524,11 @@ void pw_stream_destroy(struct pw_stream *stream);
 
 void pw_stream_add_listener(struct pw_stream *stream,
 			    struct spa_hook *listener,
-			    const struct pw_stream_events *events,
+			    const struct pw_stream_events *events,	/**< stream events. Does not take
+						 			  *  ownership, but stores the
+									  *  original struct pointer. Can be
+									  *  modified after adding, but only
+									  *  from the main loop. */
 			    void *data);
 
 /** Get the current stream state. Since 1.4 this also sets errno when the