documentation: improve misleading wording

The documentation for several gst_*_writable_structure functions stated
that they would never return NULL, without making clear that the passed
object is required to be writable. This changes the wording in those
cases to make that requirement more clear.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/1784>

diff --git a/subprojects/gst-rtsp-server/gst/rtsp-server/rtsp-token.c b/subprojects/gst-rtsp-server/gst/rtsp-server/rtsp-token.c
index 4062d30..22f96c6 100644 (file)
--- a/subprojects/gst-rtsp-server/gst/rtsp-server/rtsp-token.c
+++ b/subprojects/gst-rtsp-server/gst/rtsp-server/rtsp-token.c
@@ -239,14 +239,14 @@ gst_rtsp_token_get_structure (GstRTSPToken * token)
 
 /**
  * gst_rtsp_token_writable_structure:
- * @token: The #GstRTSPToken.
+ * @token: A writable #GstRTSPToken.
  *
  * Get a writable version of the structure.
  *
  * Returns: (transfer none): The structure of the token. The structure is still
  * owned by the token, which means that you should not free it and that the
- * pointer becomes invalid when you free the token. This function checks if
- * @token is writable and will never return %NULL.
+ * pointer becomes invalid when you free the token. This function ensures
+ * that @token is writable, and if so, will never return %NULL.
  *
  * MT safe.
  */

diff --git a/subprojects/gstreamer/gst/gstevent.c b/subprojects/gstreamer/gst/gstevent.c
index c5bf474..610037b 100644 (file)
--- a/subprojects/gstreamer/gst/gstevent.c
+++ b/subprojects/gstreamer/gst/gstevent.c
@@ -354,15 +354,15 @@ gst_event_get_structure (GstEvent * event)
 
 /**
  * gst_event_writable_structure:
- * @event: The #GstEvent.
+ * @event: A writable #GstEvent.
  *
  * Get a writable version of the structure.
  *
  * Returns: (transfer none): The structure of the event. The structure
  * is still owned by the event, which means that you should not free
  * it and that the pointer becomes invalid when you free the event.
- * This function checks if @event is writable and will never return
- * %NULL.
+ * This function ensures that @event is writable, and if so, will
+ * never return %NULL.
  *
  * MT safe.
  */

diff --git a/subprojects/gstreamer/gst/gstmessage.c b/subprojects/gstreamer/gst/gstmessage.c
index 4e6f2be..adfd8ed 100644 (file)
--- a/subprojects/gstreamer/gst/gstmessage.c
+++ b/subprojects/gstreamer/gst/gstmessage.c
@@ -1166,15 +1166,15 @@ gst_message_get_structure (GstMessage * message)
 
 /**
  * gst_message_writable_structure:
- * @message: The #GstMessage.
+ * @message: A writable #GstMessage.
  *
  * Get a writable version of the structure.
  *
  * Returns: (transfer none): The structure of the message. The structure
  * is still owned by the message, which means that you should not free
  * it and that the pointer becomes invalid when you free the message.
- * This function checks if @message is writable and will never return
- * %NULL.
+ * This function ensures that @message is writable, and if so, will
+ * never return %NULL.
  *
  * MT safe.
  *