uri-clip: Add a warning about synchronous uri discovery

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-editing-services/-/merge_requests/189>

ges/ges-asset.c

@@ -1359,7 +1359,7 @@ ges_asset_request (GType extractable_type, const gchar * id, GError ** error)
  * calling ges_init().
  *
  * Example of an asynchronous asset request:
- * |[
+ * ``` c
  * // The request callback
  * static void
  * asset_loaded_cb (GESAsset * source, GAsyncResult * res, gpointer user_data)
@@ -1369,20 +1369,20 @@ ges_asset_request (GType extractable_type, const gchar * id, GError ** error)
  *
  *   asset = ges_asset_request_finish (res, &error);
  *   if (asset) {
- *    g_print ("The file: %s is usable as a FileSource",
+ *    g_print ("The file: %s is usable as a GESUriClip",
  *        ges_asset_get_id (asset));
  *   } else {
- *    g_print ("The file: %s is *not* usable as a FileSource because: %s",
+ *    g_print ("The file: %s is *not* usable as a GESUriClip because: %s",
  *        ges_asset_get_id (source), error->message);
  *   }
  *
- *   gst_object_unref (mfs);
+ *   gst_object_unref (asset);
  * }
  *
  * // The request:
  * ges_asset_request_async (GES_TYPE_URI_CLIP, some_uri, NULL,
  *    (GAsyncReadyCallback) asset_loaded_cb, user_data);
- * ]|
+ * ```
  */
 void
 ges_asset_request_async (GType extractable_type,

ges/ges-uri-clip.c

@@ -541,6 +541,11 @@ ges_uri_clip_create_track_elements (GESClip * clip, GESTrackType type)
  *
  * Creates a new #GESUriClip for the provided @uri.
  *
+ * > **WARNING**: This function might 'discover` @uri **synchrounously**, it is
+ * > an IO and processing intensive task that you probably don't want to run in
+ * > an application mainloop. Have a look at #ges_asset_request_async to see how
+ * > to make that operation happen **asynchronously**.
+ *
  * Returns: (transfer floating) (nullable): The newly created #GESUriClip, or
  * %NULL if there was an error.
  */