Add a few gotchas to the documentation

I've learned each of these the hard way (with gdb and
lots of head scratching). Hopefully this saves others some
time:

- it looks like you can manually create struct pw_properties,
  but you really shouldn't
- pipewire keeps a pointer to any struct pw_stream_events
  without duplicating it, so it better stay valid for the
  duration of the stream

I also mentioned that you _can_ change pw_stream_events after
attaching it, as long as you do it from the loop. At least that
is my read of the code: I can't see any reason why it wouldn't
work. If I'm wrong please correct me. Also, if it works now
but it's not supported and should not be done, let me know, I can
change it to say that.

src/pipewire/properties.h

@@ -21,12 +21,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

@@ -495,7 +495,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 */
@@ -503,7 +506,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);
 
 enum pw_stream_state pw_stream_get_state(struct pw_stream *stream, const char **error);