player: Fix/add various annotations

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-bad/-/merge_requests/2538>

4 files changed, 83 insertions, 70 deletions

diff --git a/gst-libs/gst/play/gstplay-media-info.c b/gst-libs/gst/play/gstplay-media-info.c
index 9a55ed982..65c733366 100644
--- a/gst-libs/gst/play/gstplay-media-info.c
+++ b/gst-libs/gst/play/gstplay-media-info.c
@@ -70,7 +70,8 @@ gst_play_stream_info_class_init (GstPlayStreamInfoClass * klass)
  * gst_play_stream_info_get_index:
  * @info: a #GstPlayStreamInfo
  *
- * Function to get stream index from #GstPlayStreamInfo instance.
+ * Function to get stream index from #GstPlayStreamInfo instance or -1 if
+ * unknown.
  *
  * Returns: the stream index of this stream.
  * Since: 1.20
@@ -110,7 +111,7 @@ gst_play_stream_info_get_stream_type (const GstPlayStreamInfo * info)
  * gst_play_stream_info_get_tags:
  * @info: a #GstPlayStreamInfo
  *
- * Returns: (transfer none): the tags contained in this stream.
+ * Returns: (transfer none) (nullable): the tags contained in this stream.
  * Since: 1.20
  */
 GstTagList *
@@ -127,7 +128,7 @@ gst_play_stream_info_get_tags (const GstPlayStreamInfo * info)
  *
  * A string describing codec used in #GstPlayStreamInfo.
  *
- * Returns: codec string or NULL on unknown.
+ * Returns: (nullable): codec string or %NULL on unknown.
  * Since: 1.20
  */
 const gchar *
@@ -142,7 +143,8 @@ gst_play_stream_info_get_codec (const GstPlayStreamInfo * info)
  * gst_play_stream_info_get_caps:
  * @info: a #GstPlayStreamInfo
  *
- * Returns: (transfer none): the #GstCaps of the stream.
+ * Returns: (nullable) (transfer none): the #GstCaps of the stream or %NULL if
+ * unknown.
  * Since: 1.20
  */
 GstCaps *
@@ -178,7 +180,7 @@ gst_play_video_info_class_init (G_GNUC_UNUSED GstPlayVideoInfoClass * klass)
  * gst_play_video_info_get_width:
  * @info: a #GstPlayVideoInfo
  *
- * Returns: the width of video in #GstPlayVideoInfo.
+ * Returns: the width of video in #GstPlayVideoInfo or -1 if unknown.
  * Since: 1.20
  */
 gint
@@ -193,7 +195,7 @@ gst_play_video_info_get_width (const GstPlayVideoInfo * info)
  * gst_play_video_info_get_height:
  * @info: a #GstPlayVideoInfo
  *
- * Returns: the height of video in #GstPlayVideoInfo.
+ * Returns: the height of video in #GstPlayVideoInfo or -1 if unknown.
  * Since: 1.20
  */
 gint
@@ -246,7 +248,7 @@ gst_play_video_info_get_pixel_aspect_ratio (const GstPlayVideoInfo * info,
  * gst_play_video_info_get_bitrate:
  * @info: a #GstPlayVideoInfo
  *
- * Returns: the current bitrate of video in #GstPlayVideoInfo.
+ * Returns: the current bitrate of video in #GstPlayVideoInfo or -1 if unknown.
  * Since: 1.20
  */
 gint
@@ -261,7 +263,7 @@ gst_play_video_info_get_bitrate (const GstPlayVideoInfo * info)
  * gst_play_video_info_get_max_bitrate:
  * @info: a #GstPlayVideoInfo
  *
- * Returns: the maximum bitrate of video in #GstPlayVideoInfo.
+ * Returns: the maximum bitrate of video in #GstPlayVideoInfo or -1 if unknown.
  * Since: 1.20
  */
 gint
@@ -307,7 +309,7 @@ gst_play_audio_info_class_init (GstPlayAudioInfoClass * klass)
  * gst_play_audio_info_get_language:
  * @info: a #GstPlayAudioInfo
  *
- * Returns (nullable): the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or %NULL if unknown.
  * Since: 1.20
  */
 const gchar *
@@ -322,7 +324,7 @@ gst_play_audio_info_get_language (const GstPlayAudioInfo * info)
  * gst_play_audio_info_get_channels:
  * @info: a #GstPlayAudioInfo
  *
- * Returns: the number of audio channels in #GstPlayAudioInfo.
+ * Returns: the number of audio channels in #GstPlayAudioInfo or 0 if unknown.
  * Since: 1.20
  */
 gint
@@ -337,7 +339,7 @@ gst_play_audio_info_get_channels (const GstPlayAudioInfo * info)
  * gst_play_audio_info_get_sample_rate:
  * @info: a #GstPlayAudioInfo
  *
- * Returns: the audio sample rate in #GstPlayAudioInfo.
+ * Returns: the audio sample rate in #GstPlayAudioInfo or 0 if unknown.
  * Since: 1.20
  */
 gint
@@ -352,7 +354,7 @@ gst_play_audio_info_get_sample_rate (const GstPlayAudioInfo * info)
  * gst_play_audio_info_get_bitrate:
  * @info: a #GstPlayAudioInfo
  *
- * Returns: the audio bitrate in #GstPlayAudioInfo.
+ * Returns: the audio bitrate in #GstPlayAudioInfo or -1 if unknown.
  * Since: 1.20
  */
 gint
@@ -367,7 +369,7 @@ gst_play_audio_info_get_bitrate (const GstPlayAudioInfo * info)
  * gst_play_audio_info_get_max_bitrate:
  * @info: a #GstPlayAudioInfo
  *
- * Returns: the audio maximum bitrate in #GstPlayAudioInfo.
+ * Returns: the audio maximum bitrate in #GstPlayAudioInfo or -1 if unknown.
  * Since: 1.20
  */
 gint
@@ -410,7 +412,7 @@ gst_play_subtitle_info_class_init (GstPlaySubtitleInfoClass * klass)
  * gst_play_subtitle_info_get_language:
  * @info: a #GstPlaySubtitleInfo
  *
- * Returns: the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or %NULL if unknown.
  * Since: 1.20
  */
 const gchar *
@@ -765,7 +767,7 @@ gst_play_media_info_get_duration (const GstPlayMediaInfo * info)
  * gst_play_media_info_get_tags:
  * @info: a #GstPlayMediaInfo
  *
- * Returns: (transfer none): the tags contained in media info.
+ * Returns: (transfer none) (nullable): the tags contained in media info.
  * Since: 1.20
  */
 GstTagList *
@@ -780,7 +782,7 @@ gst_play_media_info_get_tags (const GstPlayMediaInfo * info)
  * gst_play_media_info_get_title:
  * @info: a #GstPlayMediaInfo
  *
- * Returns: the media title.
+ * Returns: (nullable): the media title or %NULL if unknown.
  * Since: 1.20
  */
 const gchar *
@@ -795,7 +797,7 @@ gst_play_media_info_get_title (const GstPlayMediaInfo * info)
  * gst_play_media_info_get_container_format:
  * @info: a #GstPlayMediaInfo
  *
- * Returns: the container format.
+ * Returns: (nullable): the container format or %NULL if unknown.
  * Since: 1.20
  */
 const gchar *
@@ -813,7 +815,7 @@ gst_play_media_info_get_container_format (const GstPlayMediaInfo * info)
  * Function to get the image (or preview-image) stored in taglist.
  * Application can use `gst_sample_*_()` API's to get caps, buffer etc.
  *
- * Returns: (transfer none): GstSample or NULL.
+ * Returns: (nullable) (transfer none): GstSample or %NULL.
  * Since: 1.20
  */
 GstSample *
diff --git a/gst-libs/gst/play/gstplay.c b/gst-libs/gst/play/gstplay.c
index cceea171f..79e47cd6f 100644
--- a/gst-libs/gst/play/gstplay.c
+++ b/gst-libs/gst/play/gstplay.c
@@ -610,7 +610,7 @@ gst_play_set_property (GObject * object, guint prop_id,
       self->suburi = NULL;
 
       self->uri = g_value_dup_string (value);
-      GST_DEBUG_OBJECT (self, "Set uri=%s", self->uri);
+      GST_DEBUG_OBJECT (self, "Set uri=%s", GST_STR_NULL (self->uri));
       g_mutex_unlock (&self->lock);
 
       g_main_context_invoke_full (self->context, G_PRIORITY_DEFAULT,
@@ -3098,7 +3098,7 @@ remove_seek_source (GstPlay * self)
  *
  * Gets the URI of the currently-playing stream.
  *
- * Returns: (transfer full): a string containing the URI of the
+ * Returns: (transfer full) (nullable): a string containing the URI of the
  * currently-playing stream. g_free() after usage.
  * Since: 1.20
  */
@@ -3117,7 +3117,7 @@ gst_play_get_uri (GstPlay * self)
 /**
  * gst_play_set_uri:
  * @play: #GstPlay instance
- * @uri: next URI to play.
+ * @uri: (nullable): next URI to play.
  *
  * Sets the next URI to play.
  * Since: 1.20
@@ -3133,7 +3133,7 @@ gst_play_set_uri (GstPlay * self, const gchar * val)
 /**
  * gst_play_set_subtitle_uri:
  * @play: #GstPlay instance
- * @uri: subtitle URI
+ * @uri: (nullable): subtitle URI
  *
  * Sets the external subtitle URI. This should be combined with a call to
  * gst_play_set_subtitle_track_enabled(@play, TRUE) so the subtitles are actually
@@ -3154,7 +3154,7 @@ gst_play_set_subtitle_uri (GstPlay * self, const gchar * suburi)
  *
  * current subtitle URI
  *
- * Returns: (transfer full): URI of the current external subtitle.
+ * Returns: (transfer full) (nullable): URI of the current external subtitle.
  *   g_free() after usage.
  * Since: 1.20
  */
@@ -3311,7 +3311,7 @@ gst_play_get_pipeline (GstPlay * self)
  *
  * A Function to get the current media info #GstPlayMediaInfo instance.
  *
- * Returns: (transfer full): media info instance.
+ * Returns: (transfer full) (nullable): media info instance.
  *
  * The caller should free it with g_object_unref()
  * Since: 1.20
@@ -3651,7 +3651,7 @@ gst_play_set_subtitle_track_enabled (GstPlay * self, gboolean enabled)
 /**
  * gst_play_set_visualization:
  * @play: #GstPlay instance
- * @name (nullable): visualization element obtained from
+ * @name: (nullable): visualization element obtained from
  * #gst_play_visualizations_get()
  *
  * Returns: %TRUE if the visualizations was set correctly. Otherwise,
@@ -4299,7 +4299,7 @@ gst_play_get_config (GstPlay * self)
 /**
  * gst_play_config_set_user_agent:
  * @config: a #GstPlay configuration
- * @agent: the string to use as user agent
+ * @agent: (nullable): the string to use as user agent
  *
  * Set the user agent to pass to the server if @play needs to connect
  * to a server during playback. This is typically used when playing HTTP
@@ -4324,7 +4324,7 @@ gst_play_config_set_user_agent (GstStructure * config, const gchar * agent)
  * Return the user agent which has been configured using
  * gst_play_config_set_user_agent() if any.
  *
- * Returns: (transfer full): the configured agent, or %NULL
+ * Returns: (transfer full) (nullable): the configured agent, or %NULL
  * Since: 1.20
  */
 gchar *
@@ -4557,7 +4557,7 @@ gst_play_is_play_message (GstMessage * msg)
 /**
  * gst_play_message_parse_type:
  * @msg: A #GstMessage
- * @type: (out): (optional): (transfer full): the resulting message type
+ * @type: (out) (optional): the resulting message type
  *
  * Parse the given @msg and extract its #GstPlayMessage type.
  *
@@ -4573,7 +4573,7 @@ gst_play_message_parse_type (GstMessage * msg, GstPlayMessage * type)
 /**
  * gst_play_message_parse_duration_updated:
  * @msg: A #GstMessage
- * @duration: (out): (optional): (transfer full): the resulting duration
+ * @duration: (out) (optional): the resulting duration
  *
  * Parse the given duration @msg and extract the corresponding #GstClockTime
  *
@@ -4590,7 +4590,7 @@ gst_play_message_parse_duration_updated (GstMessage * msg,
 /**
  * gst_play_message_parse_position_updated:
  * @msg: A #GstMessage
- * @position: (out): (optional): (transfer full): the resulting position
+ * @position: (out) (optional): the resulting position
  *
  * Parse the given position @msg and extract the corresponding #GstClockTime
  *
@@ -4607,7 +4607,7 @@ gst_play_message_parse_position_updated (GstMessage * msg,
 /**
  * gst_play_message_parse_state_changed:
  * @msg: A #GstMessage
- * @state: (out): (optional): (transfer full): the resulting play state
+ * @state: (out) (optional): the resulting play state
  *
  * Parse the given state @msg and extract the corresponding #GstPlayState
  *
@@ -4623,7 +4623,7 @@ gst_play_message_parse_state_changed (GstMessage * msg, GstPlayState * state)
 /**
  * gst_play_message_parse_buffering_percent:
  * @msg: A #GstMessage
- * @percent: (out): (optional): the resulting buffering percent
+ * @percent: (out) (optional): the resulting buffering percent
  *
  * Parse the given buffering-percent @msg and extract the corresponding value
  *
@@ -4639,8 +4639,8 @@ gst_play_message_parse_buffering_percent (GstMessage * msg, guint * percent)
 /**
  * gst_play_message_parse_error:
  * @msg: A #GstMessage
- * @error: (out): (optional): (transfer full): the resulting error
- * @details: (out): (optional): (transfer none): A GstStructure containing extra details about the error
+ * @error: (out) (optional) (transfer full): the resulting error
+ * @details: (out) (optional) (nullable) (transfer full): A GstStructure containing extra details about the error
  *
  * Parse the given error @msg and extract the corresponding #GError
  *
@@ -4658,8 +4658,8 @@ gst_play_message_parse_error (GstMessage * msg, GError * error,
 /**
  * gst_play_message_parse_warning:
  * @msg: A #GstMessage
- * @error: (out): (optional): (transfer full): the resulting warning
- * @details: (out): (optional): (transfer none): A GstStructure containing extra details about the error
+ * @error: (out) (optional) (transfer full): the resulting warning
+ * @details: (out) (optional) (nullable) (transfer full): A GstStructure containing extra details about the error
  *
  * Parse the given error @msg and extract the corresponding #GError warning
  *
@@ -4677,8 +4677,8 @@ gst_play_message_parse_warning (GstMessage * msg, GError * error,
 /**
  * gst_play_message_parse_video_dimensions_changed:
  * @msg: A #GstMessage
- * @width: (out): (optional): the resulting video width
- * @height: (out): (optional): the resulting video height
+ * @width: (out) (optional): the resulting video width
+ * @height: (out) (optional): the resulting video height
  *
  * Parse the given @msg and extract the corresponding video dimensions
  *
@@ -4697,7 +4697,7 @@ gst_play_message_parse_video_dimensions_changed (GstMessage * msg,
 /**
  * gst_play_message_parse_media_info_updated:
  * @msg: A #GstMessage
- * @info: (out): (optional): (transfer full): the resulting media info
+ * @info: (out) (optional) (transfer full): the resulting media info
  *
  * Parse the given @msg and extract the corresponding media information
  *
@@ -4714,7 +4714,7 @@ gst_play_message_parse_media_info_updated (GstMessage * msg,
 /**
  * gst_play_message_parse_volume_changed:
  * @msg: A #GstMessage
- * @volume: (out): (optional): the resulting audio volume
+ * @volume: (out) (optional): the resulting audio volume
  *
  * Parse the given @msg and extract the corresponding audio volume
  *
@@ -4730,7 +4730,7 @@ gst_play_message_parse_volume_changed (GstMessage * msg, gdouble * volume)
 /**
  * gst_play_message_parse_muted_changed:
  * @msg: A #GstMessage
- * @muted: (out): (optional): the resulting audio muted state
+ * @muted: (out) (optional): the resulting audio muted state
  *
  * Parse the given @msg and extract the corresponding audio muted state
  *
diff --git a/gst-libs/gst/player/gstplayer-media-info.c b/gst-libs/gst/player/gstplayer-media-info.c
index 2be22a5ad..f2af40bf2 100644
--- a/gst-libs/gst/player/gstplayer-media-info.c
+++ b/gst-libs/gst/player/gstplayer-media-info.c
@@ -64,7 +64,8 @@ gst_player_stream_info_class_init (GstPlayerStreamInfoClass * klass)
  * gst_player_stream_info_get_index:
  * @info: a #GstPlayerStreamInfo
  *
- * Function to get stream index from #GstPlayerStreamInfo instance.
+ * Function to get stream index from #GstPlayerStreamInfo instance or -1 if
+ * unknown.
  *
  * Returns: the stream index of this stream.
  */
@@ -97,7 +98,7 @@ gst_player_stream_info_get_stream_type (const GstPlayerStreamInfo * info)
  * gst_player_stream_info_get_tags:
  * @info: a #GstPlayerStreamInfo
  *
- * Returns: (transfer none): the tags contained in this stream.
+ * Returns: (transfer none) (nullable): the tags contained in this stream.
  */
 GstTagList *
 gst_player_stream_info_get_tags (const GstPlayerStreamInfo * info)
@@ -113,7 +114,7 @@ gst_player_stream_info_get_tags (const GstPlayerStreamInfo * info)
  *
  * A string describing codec used in #GstPlayerStreamInfo.
  *
- * Returns: codec string or NULL on unknown.
+ * Returns: (nullable): codec string or %NULL on unknown.
  */
 const gchar *
 gst_player_stream_info_get_codec (const GstPlayerStreamInfo * info)
@@ -127,7 +128,7 @@ gst_player_stream_info_get_codec (const GstPlayerStreamInfo * info)
  * gst_player_stream_info_get_caps:
  * @info: a #GstPlayerStreamInfo
  *
- * Returns: (transfer none): the #GstCaps of the stream.
+ * Returns: (transfer none) (nullable): the #GstCaps of the stream.
  */
 GstCaps *
 gst_player_stream_info_get_caps (const GstPlayerStreamInfo * info)
@@ -157,7 +158,7 @@ gst_player_video_info_class_init (G_GNUC_UNUSED GstPlayerVideoInfoClass * klass)
  * gst_player_video_info_get_width:
  * @info: a #GstPlayerVideoInfo
  *
- * Returns: the width of video in #GstPlayerVideoInfo.
+ * Returns: the width of video in #GstPlayerVideoInfo or -1 if unknown.
  */
 gint
 gst_player_video_info_get_width (const GstPlayerVideoInfo * info)
@@ -171,7 +172,7 @@ gst_player_video_info_get_width (const GstPlayerVideoInfo * info)
  * gst_player_video_info_get_height:
  * @info: a #GstPlayerVideoInfo
  *
- * Returns: the height of video in #GstPlayerVideoInfo.
+ * Returns: the height of video in #GstPlayerVideoInfo or -1 if unknown.
  */
 gint
 gst_player_video_info_get_height (const GstPlayerVideoInfo * info)
@@ -219,7 +220,8 @@ gst_player_video_info_get_pixel_aspect_ratio (const GstPlayerVideoInfo * info,
  * gst_player_video_info_get_bitrate:
  * @info: a #GstPlayerVideoInfo
  *
- * Returns: the current bitrate of video in #GstPlayerVideoInfo.
+ * Returns: the current bitrate of video in #GstPlayerVideoInfo or -1 if
+ * unknown.
  */
 gint
 gst_player_video_info_get_bitrate (const GstPlayerVideoInfo * info)
@@ -233,7 +235,8 @@ gst_player_video_info_get_bitrate (const GstPlayerVideoInfo * info)
  * gst_player_video_info_get_max_bitrate:
  * @info: a #GstPlayerVideoInfo
  *
- * Returns: the maximum bitrate of video in #GstPlayerVideoInfo.
+ * Returns: the maximum bitrate of video in #GstPlayerVideoInfo or -1 if
+ * unknown.
  */
 gint
 gst_player_video_info_get_max_bitrate (const GstPlayerVideoInfo * info)
@@ -275,7 +278,7 @@ gst_player_audio_info_class_init (GstPlayerAudioInfoClass * klass)
  * gst_player_audio_info_get_language:
  * @info: a #GstPlayerAudioInfo
  *
- * Returns (nullable): the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or NULL if unknown.
  */
 const gchar *
 gst_player_audio_info_get_language (const GstPlayerAudioInfo * info)
@@ -289,7 +292,8 @@ gst_player_audio_info_get_language (const GstPlayerAudioInfo * info)
  * gst_player_audio_info_get_channels:
  * @info: a #GstPlayerAudioInfo
  *
- * Returns: the number of audio channels in #GstPlayerAudioInfo.
+ * Returns: the number of audio channels in #GstPlayerAudioInfo or 0 if
+ * unknown.
  */
 gint
 gst_player_audio_info_get_channels (const GstPlayerAudioInfo * info)
@@ -303,7 +307,7 @@ gst_player_audio_info_get_channels (const GstPlayerAudioInfo * info)
  * gst_player_audio_info_get_sample_rate:
  * @info: a #GstPlayerAudioInfo
  *
- * Returns: the audio sample rate in #GstPlayerAudioInfo.
+ * Returns: the audio sample rate in #GstPlayerAudioInfo or 0 if unknown.
  */
 gint
 gst_player_audio_info_get_sample_rate (const GstPlayerAudioInfo * info)
@@ -317,7 +321,7 @@ gst_player_audio_info_get_sample_rate (const GstPlayerAudioInfo * info)
  * gst_player_audio_info_get_bitrate:
  * @info: a #GstPlayerAudioInfo
  *
- * Returns: the audio bitrate in #GstPlayerAudioInfo.
+ * Returns: the audio bitrate in #GstPlayerAudioInfo or -1 if unknown.
  */
 gint
 gst_player_audio_info_get_bitrate (const GstPlayerAudioInfo * info)
@@ -331,7 +335,7 @@ gst_player_audio_info_get_bitrate (const GstPlayerAudioInfo * info)
  * gst_player_audio_info_get_max_bitrate:
  * @info: a #GstPlayerAudioInfo
  *
- * Returns: the audio maximum bitrate in #GstPlayerAudioInfo.
+ * Returns: the audio maximum bitrate in #GstPlayerAudioInfo or -1 if unknown.
  */
 gint
 gst_player_audio_info_get_max_bitrate (const GstPlayerAudioInfo * info)
@@ -373,7 +377,7 @@ gst_player_subtitle_info_class_init (GstPlayerSubtitleInfoClass * klass)
  * gst_player_subtitle_info_get_language:
  * @info: a #GstPlayerSubtitleInfo
  *
- * Returns: the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or %NULL if unknown.
  */
 const gchar *
 gst_player_subtitle_info_get_language (const GstPlayerSubtitleInfo * info)
@@ -741,7 +745,7 @@ gst_player_media_info_get_audio_streams (const GstPlayerMediaInfo * info)
  * gst_player_media_info_get_duration:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: duration of the media.
+ * Returns: duration of the media or %GST_CLOCK_TIME_NONE if unknown.
  */
 GstClockTime
 gst_player_media_info_get_duration (const GstPlayerMediaInfo * info)
@@ -755,7 +759,7 @@ gst_player_media_info_get_duration (const GstPlayerMediaInfo * info)
  * gst_player_media_info_get_tags:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: (transfer none): the tags contained in media info.
+ * Returns: (transfer none) (nullable): the tags contained in media info.
  */
 GstTagList *
 gst_player_media_info_get_tags (const GstPlayerMediaInfo * info)
@@ -769,7 +773,7 @@ gst_player_media_info_get_tags (const GstPlayerMediaInfo * info)
  * gst_player_media_info_get_title:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: the media title.
+ * Returns: (nullable): the media title or %NULL if unknown.
  */
 const gchar *
 gst_player_media_info_get_title (const GstPlayerMediaInfo * info)
@@ -783,7 +787,7 @@ gst_player_media_info_get_title (const GstPlayerMediaInfo * info)
  * gst_player_media_info_get_container_format:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: the container format.
+ * Returns: (nullable): the container format or %NULL if unknown.
  */
 const gchar *
 gst_player_media_info_get_container_format (const GstPlayerMediaInfo * info)
@@ -800,7 +804,7 @@ gst_player_media_info_get_container_format (const GstPlayerMediaInfo * info)
  * Function to get the image (or preview-image) stored in taglist.
  * Application can use `gst_sample_*_()` API's to get caps, buffer etc.
  *
- * Returns: (transfer none): GstSample or NULL.
+ * Returns: (transfer none) (nullable): GstSample or %NULL.
  */
 GstSample *
 gst_player_media_info_get_image_sample (const GstPlayerMediaInfo * info)
@@ -814,7 +818,8 @@ gst_player_media_info_get_image_sample (const GstPlayerMediaInfo * info)
  * gst_player_media_info_get_number_of_streams:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: number of total streams.
+ * Returns: number of total streams or 0 if unknown.
+ *
  * Since: 1.12
  */
 guint
@@ -829,7 +834,8 @@ gst_player_media_info_get_number_of_streams (const GstPlayerMediaInfo * info)
  * gst_player_media_info_get_number_of_video_streams:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: number of video streams.
+ * Returns: number of video streams or 0 if unknown.
+ *
  * Since: 1.12
  */
 guint
@@ -845,7 +851,8 @@ gst_player_media_info_get_number_of_video_streams (const GstPlayerMediaInfo *
  * gst_player_media_info_get_number_of_audio_streams:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: number of audio streams.
+ * Returns: number of audio streams or 0 if unknown.
+ *
  * Since: 1.12
  */
 guint
@@ -861,7 +868,8 @@ gst_player_media_info_get_number_of_audio_streams (const GstPlayerMediaInfo *
  * gst_player_media_info_get_number_of_subtitle_streams:
  * @info: a #GstPlayerMediaInfo
  *
- * Returns: number of subtitle streams.
+ * Returns: number of subtitle streams or 0 if unknown.
+ *
  * Since: 1.12
  */
 guint gst_player_media_info_get_number_of_subtitle_streams
diff --git a/gst-libs/gst/player/gstplayer.c b/gst-libs/gst/player/gstplayer.c
index 5f64f1e77..cbc9501a3 100644
--- a/gst-libs/gst/player/gstplayer.c
+++ b/gst-libs/gst/player/gstplayer.c
@@ -743,7 +743,7 @@ gst_player_get_uri (GstPlayer * self)
 /**
  * gst_player_set_uri:
  * @player: #GstPlayer instance
- * @uri: next URI to play.
+ * @uri: (nullable): next URI to play.
  *
  * Sets the next URI to play.
  */
@@ -758,7 +758,7 @@ gst_player_set_uri (GstPlayer * self, const gchar * val)
 /**
  * gst_player_set_subtitle_uri:
  * @player: #GstPlayer instance
- * @uri: subtitle URI
+ * @uri: (nullable): subtitle URI
  *
  * Sets the external subtitle URI. This should be combined with a call to
  * gst_player_set_subtitle_track_enabled(@player, TRUE) so the subtitles are actually
@@ -931,7 +931,7 @@ gst_player_get_pipeline (GstPlayer * self)
  *
  * A Function to get the current media info #GstPlayerMediaInfo instance.
  *
- * Returns: (transfer full): media info instance.
+ * Returns: (transfer full) (nullable): media info instance.
  *
  * The caller should free it with g_object_unref()
  */
@@ -944,6 +944,9 @@ gst_player_get_media_info (GstPlayer * self)
   g_return_val_if_fail (GST_IS_PLAYER (self), NULL);
 
   info = gst_play_get_media_info (self->play);
+  if (!info)
+    return NULL;
+
   ret = gst_player_media_info_wrapped (info);
   g_object_unref (info);
   return ret;
@@ -1126,7 +1129,7 @@ gst_player_set_subtitle_track_enabled (GstPlayer * self, gboolean enabled)
 /**
  * gst_player_set_visualization:
  * @player: #GstPlayer instance
- * @name (nullable): visualization element obtained from
+ * @name: (nullable): visualization element obtained from
  * #gst_player_visualizations_get()
  *
  * Returns: %TRUE if the visualizations was set correctly. Otherwise,
@@ -1581,7 +1584,7 @@ gst_player_get_config (GstPlayer * self)
 /**
  * gst_player_config_set_user_agent:
  * @config: a #GstPlayer configuration
- * @agent: the string to use as user agent
+ * @agent: (nullable): the string to use as user agent
  *
  * Set the user agent to pass to the server if @player needs to connect
  * to a server during playback. This is typically used when playing HTTP
@@ -1606,7 +1609,7 @@ gst_player_config_set_user_agent (GstStructure * config, const gchar * agent)
  * Return the user agent which has been configured using
  * gst_player_config_set_user_agent() if any.
  *
- * Returns: (transfer full): the configured agent, or %NULL
+ * Returns: (transfer full) (nullable): the configured agent, or %NULL
  *
  * Since: 1.10
  */