ges: Add/fix various annotations

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

subprojects/gst-editing-services/ges/ges-asset.c

@@ -1544,7 +1544,7 @@ ges_asset_get_id (GESAsset * self)
 /**
  * ges_asset_extract:
  * @self: The #GESAsset to extract an object from
- * @error: (allow-none): An error to be set in case something goes wrong,
+ * @error: (optional): An error to be set in case something goes wrong,
  * or %NULL to ignore
  *
  * Extracts a new #GESAsset:extractable-type object from the asset. The

subprojects/gst-editing-services/ges/ges-clip.c

@@ -3342,7 +3342,7 @@ ges_clip_set_top_effect_index (GESClip * clip, GESBaseEffect * effect,
  * @clip: The #GESClip to split
  * @position: The timeline position at which to perform the split, between
  * the start and end of the clip
- * @error: (nullable): Return location for an error
+ * @error: (optional) (nullable): Return location for an error
  *
  * Splits a clip at the given timeline position into two clips. The clip
  * must already have a #GESClip:layer.
@@ -3374,6 +3374,7 @@ ges_clip_set_top_effect_index (GESClip * clip, GESBaseEffect * effect,
  *
  * Returns: (transfer none) (nullable): The newly created clip resulting
  * from the splitting @clip, or %NULL if @clip can't be split.
+ *
  * Since: 1.18
  */
 GESClip *
@@ -3604,7 +3605,7 @@ ges_clip_get_supported_formats (GESClip * clip)
  * clip, but this method is not intended to be used to create the core
  * elements of the clip.
  *
- * Returns: (transfer none)(allow-none): The newly created element, or
+ * Returns: (transfer none) (nullable): The newly created element, or
  * %NULL if an error occurred.
  */
 /* FIXME: this is not used elsewhere in the GES library */
@@ -4401,7 +4402,7 @@ ges_clip_get_timeline_time_from_source_frame (GESClip * clip,
  * @clip: A #GESClip
  * @child: A child of @clip
  * @track: The track to add @child to
- * @error: (nullable): Return location for an error
+ * @error: (optional) (nullable): Return location for an error
  *
  * Adds the track element child of the clip to a specific track.
  *

subprojects/gst-editing-services/ges/ges-container.c

@@ -986,7 +986,7 @@ ges_container_ungroup (GESContainer * container, gboolean recursive)
 
 /**
  * ges_container_group:
- * @containers: (transfer none)(element-type GESContainer) (allow-none):
+ * @containers: (transfer none) (element-type GESContainer) (nullable):
  * The #GESContainer-s to group
  *
  * Groups the containers into a single container by merging them. The
@@ -1000,7 +1000,7 @@ ges_container_ungroup (GESContainer * container, gboolean recursive)
  * elements is not a #GESClip, this method will try to create a #GESGroup
  * instead.
  *
- * Returns: (transfer floating): The container created by merging
+ * Returns: (transfer floating) (nullable): The container created by merging
  * @containers, or %NULL if they could not be merged into a single
  * container.
  */

subprojects/gst-editing-services/ges/ges-layer.c

@@ -917,7 +917,7 @@ ges_layer_add_asset_full (GESLayer * layer,
  *
  * See ges_layer_add_asset_full(), which also gives an error.
  *
- * Returns: (transfer none): The newly created clip.
+ * Returns: (transfer none) (nullable): The newly created clip.
  */
 GESClip *
 ges_layer_add_asset (GESLayer * layer,

subprojects/gst-editing-services/ges/ges-meta-container.c

@@ -523,8 +523,7 @@ ges_meta_container_set_marker_list (GESMetaContainer * container,
  *
  * Serializes the set metadata fields of the meta container to a string.
  *
- * Returns: (transfer full): A serialized @container, or %NULL if an error
+ * Returns: (transfer full): A serialized @container.
- * occurred.
  */
 gchar *
 ges_meta_container_metas_to_string (GESMetaContainer * container)
@@ -1115,7 +1114,7 @@ ges_meta_container_get_float (GESMetaContainer * container,
  * container. If the field does not have a set value, or it is of the
  * wrong type, the method will fail.
  *
- * Returns: (transfer none): The string value under @meta_item, or %NULL
+ * Returns: (transfer none) (nullable): The string value under @meta_item, or %NULL
  * if it could not be fetched.
  */
 const gchar *
@@ -1139,7 +1138,7 @@ ges_meta_container_get_string (GESMetaContainer * container,
  *
  * Gets the current value of the specified field of the meta container.
  *
- * Returns: (transfer none): The value under @key, or %NULL if @container
+ * Returns: (transfer none) (nullable): The value under @key, or %NULL if @container
  * does not have the field set.
  */
 const GValue *
@@ -1164,7 +1163,7 @@ ges_meta_container_get_meta (GESMetaContainer * container, const gchar * key)
  * container. If the field does not have a set value, or it is of the
  * wrong type, the method will fail.
  *
- * Returns: (transfer full): A copy of the marker list value under @key,
+ * Returns: (transfer full) (nullable): A copy of the marker list value under @key,
  * or %NULL if it could not be fetched.
  * Since: 1.18
  */
@@ -1193,7 +1192,7 @@ ges_meta_container_get_marker_list (GESMetaContainer * container,
  * ges_meta_container_get_date:
  * @container: A #GESMetaContainer
  * @meta_item: The key for the @container field to get
- * @dest: (out): Destination into which the value under @meta_item
+ * @dest: (out) (optional) (transfer full): Destination into which the value under @meta_item
  * should be copied.
  *
  * Gets the current date value of the specified field of the meta
@@ -1209,7 +1208,7 @@ CREATE_GETTER (date, GDate **);
  * ges_meta_container_get_date_time:
  * @container: A #GESMetaContainer
  * @meta_item: The key for the @container field to get
- * @dest: (out): Destination into which the value under @meta_item
+ * @dest: (out) (optional) (transfer full): Destination into which the value under @meta_item
  * should be copied.
  *
  * Gets the current date time value of the specified field of the meta

subprojects/gst-editing-services/ges/ges-pipeline.c

@@ -1299,7 +1299,7 @@ ges_pipeline_set_mode (GESPipeline * pipeline, GESPipelineFlags mode)
  * the image is used. You can retrieve these caps from the returned sample
  * with gst_sample_get_caps().
  *
- * Returns: (transfer full): A sample of @self's current image preview in
+ * Returns: (transfer full) (nullable): A sample of @self's current image preview in
  * the format given by @caps, or %NULL if an error prevented fetching the
  * sample.
  */
@@ -1331,7 +1331,7 @@ ges_pipeline_get_thumbnail (GESPipeline * self, GstCaps * caps)
  * native size
  * @format: The desired mime type (for example, "image/jpeg")
  * @location: The path to save the thumbnail to
- * @error: (out) (allow-none) (transfer full): An error to be set in case
+ * @error: (out) (optional) (transfer full): An error to be set in case
  * something goes wrong, or %NULL to ignore
  *
  * Saves the currently displayed image of the pipeline in preview to the
@@ -1397,7 +1397,7 @@ ges_pipeline_save_thumbnail (GESPipeline * self, int width, int
  *
  * See ges_pipeline_get_thumbnail().
  *
- * Returns: (transfer full): A sample of @self's current image preview in
+ * Returns: (transfer full) (nullable): A sample of @self's current image preview in
  * the "RGB" format, scaled to @width and @height, or %NULL if an error
  * prevented fetching the sample.
  */
@@ -1431,7 +1431,7 @@ ges_pipeline_get_thumbnail_rgb24 (GESPipeline * self, gint width, gint height)
  *
  * Gets the #GESPipeline:video-sink of the pipeline.
  *
- * Returns: (transfer full): The video sink used by @self for preview.
+ * Returns: (transfer full) (nullable): The video sink used by @self for preview.
  */
 GstElement *
 ges_pipeline_preview_get_video_sink (GESPipeline * self)
@@ -1449,7 +1449,7 @@ ges_pipeline_preview_get_video_sink (GESPipeline * self)
 /**
  * ges_pipeline_preview_set_video_sink:
  * @self: A #GESPipeline in #GST_STATE_NULL
- * @sink: (transfer none): A video sink for @self to use for preview
+ * @sink: (transfer none) (nullable): A video sink for @self to use for preview
  *
  * Sets the #GESPipeline:video-sink of the pipeline.
  */
@@ -1468,7 +1468,7 @@ ges_pipeline_preview_set_video_sink (GESPipeline * self, GstElement * sink)
  *
  * Gets the #GESPipeline:audio-sink of the pipeline.
  *
- * Returns: (transfer full): The audio sink used by @self for preview.
+ * Returns: (transfer full) (nullable): The audio sink used by @self for preview.
  */
 GstElement *
 ges_pipeline_preview_get_audio_sink (GESPipeline * self)
@@ -1486,7 +1486,7 @@ ges_pipeline_preview_get_audio_sink (GESPipeline * self)
 /**
  * ges_pipeline_preview_set_audio_sink:
  * @self: A #GESPipeline in #GST_STATE_NULL
- * @sink: (transfer none): A audio sink for @self to use for preview
+ * @sink: (transfer none) (nullable): A audio sink for @self to use for preview
  *
  * Sets the #GESPipeline:audio-sink of the pipeline.
  */

subprojects/gst-editing-services/ges/ges-project.c

@@ -575,7 +575,7 @@ ges_project_class_init (GESProjectClass * klass)
    * }
    * ]|
    *
-   * Returns: (transfer full) (allow-none): The new URI of @wrong_asset
+   * Returns: (transfer full) (nullable): The new URI of @wrong_asset
    */
   _signals[MISSING_URI_SIGNAL] =
       g_signal_new ("missing-uri", G_TYPE_FROM_CLASS (klass),
@@ -996,7 +996,7 @@ ges_project_remove_asset (GESProject * project, GESAsset * asset)
  * @extractable_type: The extractable_type of the asset
  * to retrieve from @object
  *
- * Returns: (transfer full) (allow-none): The #GESAsset with
+ * Returns: (transfer full) (nullable): The #GESAsset with
  * @id or %NULL if no asset with @id as an ID
  */
 GESAsset *

subprojects/gst-editing-services/ges/ges-screenshot.c

@@ -33,7 +33,7 @@
  *
  * Get the last buffer @playsink showed
  *
- * Returns: (transfer full): A #GstSample containing the last frame from
+ * Returns: (transfer full) (nullable): A #GstSample containing the last frame from
  * @playsink in the format defined by the @caps
  *
  * Deprecated: 1.18: Use the "convert-sample" action signal of

subprojects/gst-editing-services/ges/ges-text-overlay-clip.c

@@ -257,7 +257,7 @@ ges_text_overlay_clip_init (GESTextOverlayClip * self)
 /**
  * ges_text_overlay_clip_set_text:
  * @self: the #GESTextOverlayClip* to set text on
- * @text: the text to render. an internal copy of this text will be
+ * @text: (nullable): the text to render. an internal copy of this text will be
  * made.
  *
  * Sets the text this clip will render.
@@ -288,7 +288,7 @@ ges_text_overlay_clip_set_text (GESTextOverlayClip * self, const gchar * text)
 /**
  * ges_text_overlay_clip_set_font_desc:
  * @self: the #GESTextOverlayClip*
- * @font_desc: the pango font description
+ * @font_desc: (nullable): the pango font description
  *
  * Sets the pango font description of the text
  *
@@ -459,7 +459,7 @@ ges_text_overlay_clip_set_ypos (GESTextOverlayClip * self, gdouble position)
  *
  * Get the text currently set on @self.
  *
- * Returns: The text currently set on @self.
+ * Returns: (nullable): The text currently set on @self.
  *
  */
 const gchar *
@@ -474,7 +474,7 @@ ges_text_overlay_clip_get_text (GESTextOverlayClip * self)
  *
  * Get the pango font description used by @self.
  *
- * Returns: The pango font description used by @self.
+ * Returns: (nullable): The pango font description used by @self.
  */
 const char *
 ges_text_overlay_clip_get_font_desc (GESTextOverlayClip * self)

subprojects/gst-editing-services/ges/ges-text-overlay.c

@@ -194,7 +194,7 @@ ges_text_overlay_create_element (GESTrackElement * track_element)
 /**
  * ges_text_overlay_set_text:
  * @self: the #GESTextOverlay* to set text on
- * @text: the text to render. an internal copy of this text will be
+ * @text: (nullable): the text to render. an internal copy of this text will be
  * made.
  *
  * Sets the text this track element will render.
@@ -216,7 +216,7 @@ ges_text_overlay_set_text (GESTextOverlay * self, const gchar * text)
 /**
  * ges_text_overlay_set_font_desc:
  * @self: the #GESTextOverlay
- * @font_desc: the pango font description
+ * @font_desc: (nullable): the pango font description
  *
  * Sets the pango font description of the text this track element
  * will render.
@@ -331,7 +331,7 @@ ges_text_overlay_set_ypos (GESTextOverlay * self, gdouble position)
  *
  * Get the text currently set on @source.
  *
- * Returns: The text currently set on @source.
+ * Returns: (nullable): The text currently set on @source.
  */
 const gchar *
 ges_text_overlay_get_text (GESTextOverlay * self)
@@ -345,7 +345,7 @@ ges_text_overlay_get_text (GESTextOverlay * self)
  *
  * Get the pango font description currently set on @source.
  *
- * Returns: The pango font description currently set on @source.
+ * Returns: (nullable): The pango font description currently set on @source.
  */
 const char *
 ges_text_overlay_get_font_desc (GESTextOverlay * self)

subprojects/gst-editing-services/ges/ges-timeline-element.c

@@ -1585,8 +1585,7 @@ ges_timeline_element_trim (GESTimelineElement * self, GstClockTime start)
  * @self, but should be thought of as an intermediate object used for a
  * single paste operation.
  *
- * Returns: (transfer floating): The newly create element,
+ * Returns: (transfer floating): The newly create element, copied from @self.
- * copied from @self.
  */
 G_GNUC_BEGIN_IGNORE_DEPRECATIONS;       /* Start ignoring GParameter deprecation */
 GESTimelineElement *
@@ -1668,7 +1667,7 @@ ges_timeline_element_get_toplevel_parent (GESTimelineElement * self)
  *
  * Gets the #GESTimelineElement:name for the element.
  *
- * Returns: (transfer full): The name of @self.
+ * Returns: (transfer full) (nullable): The name of @self.
  */
 gchar *
 ges_timeline_element_get_name (GESTimelineElement * self)
@@ -1681,7 +1680,7 @@ ges_timeline_element_get_name (GESTimelineElement * self)
 /**
  * ges_timeline_element_set_name:
  * @self: A #GESTimelineElement
- * @name: (allow-none): The name @self should take
+ * @name: (nullable): The name @self should take
  *
  * Sets the #GESTimelineElement:name for the element. If %NULL is given
  * for @name, then the library will instead generate a new name based on
@@ -2372,7 +2371,7 @@ ges_timeline_element_get_layer_priority (GESTimelineElement * self)
  * @edge: The edge of @self where the edit should occur
  * @position: The edit position: a new location for the edge of @self
  * (in nanoseconds) in the timeline coordinates
- * @error: (nullable): Return location for an error
+ * @error: (optional): Return location for an error
  *
  * Edits the element within its timeline by adjusting its
  * #GESTimelineElement:start, #GESTimelineElement:duration or

subprojects/gst-editing-services/ges/ges-timeline.c

@@ -857,7 +857,7 @@ ges_timeline_class_init (GESTimelineClass * klass)
    * Simplified version of #GESTimeline::select-tracks-for-object which only
    * allows @track_element to be added to a single #GESTrack.
    *
-   * Returns: (transfer full): A track to put @track_element into, or %NULL if
+   * Returns: (transfer full) (nullable): A track to put @track_element into, or %NULL if
    * it should be discarded.
    *
    * Since: 1.18
@@ -2178,12 +2178,12 @@ ges_timeline_new (void)
 /**
  * ges_timeline_new_from_uri:
  * @uri: The URI to load from
- * @error: (out) (allow-none): An error to be set if loading fails, or
+ * @error: (out) (optional): An error to be set if loading fails, or
  * %NULL to ignore
  *
  * Creates a timeline from the given URI.
  *
- * Returns: (transfer floating) (nullable): A new timeline if the uri was loaded
+ * Returns: (transfer floating): A new timeline if the uri was loaded
  * successfully, or %NULL if the uri could not be loaded.
  */
 GESTimeline *

subprojects/gst-editing-services/ges/ges-title-clip.c

@@ -280,7 +280,7 @@ ges_title_clip_init (GESTitleClip * self)
 /**
  * ges_title_clip_set_text:
  * @self: the #GESTitleClip* to set text on
- * @text: the text to render. an internal copy of this text will be
+ * @text: (nullable): the text to render. an internal copy of this text will be
  * made.
  *
  * Sets the text this clip will render.
@@ -303,7 +303,7 @@ ges_title_clip_set_text (GESTitleClip * self, const gchar * text)
 /**
  * ges_title_clip_set_font_desc:
  * @self: the #GESTitleClip*
- * @font_desc: the pango font description
+ * @font_desc: (nullable): the pango font description
  *
  * Sets the pango font description of the text.
  *
@@ -466,7 +466,7 @@ ges_title_clip_set_ypos (GESTitleClip * self, gdouble position)
  *
  * Get the text currently set on @self.
  *
- * Returns: The text currently set on @self.
+ * Returns: (transfer full) (nullable): The text currently set on @self.
  *
  * Deprecated:1.6: use #ges_timeline_element_get_children_properties instead.
  * See #GESTitleSource for more information about exposed properties
@@ -488,7 +488,7 @@ ges_title_clip_get_text (GESTitleClip * self)
  *
  * Get the pango font description used by @self.
  *
- * Returns: The pango font description used by @self.
+ * Returns: (transfer full) (nullable): The pango font description used by @self.
  *
  * Deprecated:1.6: use #ges_timeline_element_get_children_properties instead.
  * See #GESTitleSource for more information about exposed properties

subprojects/gst-editing-services/ges/ges-title-source.c

@@ -240,7 +240,7 @@ ges_title_source_create_source (GESSource * source)
 /**
  * ges_title_source_set_text:
  * @self: the #GESTitleSource* to set text on
- * @text: the text to render. an internal copy of this text will be
+ * @text: (nullable): the text to render. an internal copy of this text will be
  * made.
  *
  * Sets the text this track element will render.
@@ -265,7 +265,7 @@ ges_title_source_set_text (GESTitleSource * self, const gchar * text)
 /**
  * ges_title_source_set_font_desc:
  * @self: the #GESTitleSource
- * @font_desc: the pango font description
+ * @font_desc: (nullable): the pango font description
  *
  * Set the pango font description this source will use to render
  * the text.
@@ -392,7 +392,7 @@ ges_title_source_set_ypos (GESTitleSource * self, gdouble position)
  *
  * Get the text currently set on the @source.
  *
- * Returns: (transfer full): The text currently set on the @source.
+ * Returns: (transfer full) (nullable): The text currently set on the @source.
  *
  * Deprecated: 1.16: Use ges_timeline_element_get_child_property instead
  * (this actually returns a newly allocated string)
@@ -414,7 +414,7 @@ ges_title_source_get_text (GESTitleSource * source)
  *
  * Get the pango font description used by @source.
  *
- * Returns: (transfer full): The pango font description used by this
+ * Returns: (transfer full) (nullable): The pango font description used by this
  * @source.
  *
  * Deprecated: 1.16: Use ges_timeline_element_get_child_property instead

subprojects/gst-editing-services/ges/ges-track-element.c

@@ -1317,7 +1317,7 @@ ges_track_element_get_nleobject (GESTrackElement * object)
  * Get the #GstElement that the track element's underlying nleobject
  * controls.
  *
- * Returns: (transfer none): The #GstElement being controlled by the
+ * Returns: (transfer none) (nullable): The #GstElement being controlled by the
  * nleobject that @object wraps.
  */
 GstElement *

subprojects/gst-editing-services/ges/ges-track.c

@@ -1333,7 +1333,7 @@ ges_track_remove_element (GESTrack * track, GESTrackElement * object)
  *
  * Get the #GESTrack:caps of the track.
  *
- * Returns: The caps of @track.
+ * Returns: (nullable): The caps of @track.
  */
 const GstCaps *
 ges_track_get_caps (GESTrack * track)
@@ -1443,7 +1443,7 @@ ges_track_set_create_element_for_gap_func (GESTrack * track,
  *
  * Gets the #GESTrack:restriction-caps of the track.
  *
- * Returns: (transfer full): The restriction-caps of @track.
+ * Returns: (transfer full) (nullable): The restriction-caps of @track.
  *
  * Since: 1.18
  */

subprojects/gst-editing-services/ges/ges-utils.c

@@ -44,8 +44,7 @@ static GstElementFactory *compositor_factory = NULL;
  * Creates a new timeline containing a single #GESAudioTrack and a
  * single #GESVideoTrack.
  *
- * Returns: (transfer floating): The new timeline, or %NULL if the tracks
+ * Returns: (transfer floating): The new timeline.
- * could not be created and added.
  */
 
 GESTimeline *