From 5ab9c5a203ceae7282bcb676db348422a0756616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Laignel?= Date: Thu, 14 Nov 2024 11:46:24 +0100 Subject: [PATCH] gst: deprecate `maybe_field()` setters in favor of `field_if_some()` Some builder convenience setters where added to work with `Option`al values. This is the case for the `Pad` builder setter `maybe_name()` which was introduced as part of [this MR]. Then [more convenience setters] were discussed and [it was decided] to use `field_if_some()` instead of `maybe_field()`. Existing `maybe_field()`s were kept for backward compatibility. This commit marks them as deprecated, referring to the matching `field_if_some()`. [this MR]: https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/merge_requests/1255 [more convenience setters]: https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/issues/499 [it was decided]: https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/-/issues/499#note_2364820 Part-of: --- gstreamer/src/ghost_pad.rs | 12 ++++++------ gstreamer/src/pad.rs | 4 +++- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/gstreamer/src/ghost_pad.rs b/gstreamer/src/ghost_pad.rs index 085f89846..d0b6aed97 100644 --- a/gstreamer/src/ghost_pad.rs +++ b/gstreamer/src/ghost_pad.rs @@ -103,7 +103,7 @@ impl GhostPad { /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`, /// the `GhostPad` will automatically be named after the `name_template`. /// - /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name) + /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::name_if_some`](crate::PadBuilder::name_if_some) /// to specify a different name. /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` @@ -143,7 +143,7 @@ impl GhostPad { /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`, /// the `GhostPad` will automatically be named after the `name_template`. /// - /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name) + /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::name_if_some`](crate::PadBuilder::name_if_some) /// to specify a different name. /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` @@ -177,7 +177,7 @@ impl GhostPad { /// /// The `GhostPad` will automatically be named after the `target` `name`. /// - /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name) + /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::name_if_some`](crate::PadBuilder::name_if_some) /// to specify a different name. /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` @@ -201,7 +201,7 @@ impl GhostPad { /// /// If the `name_template` is a wildcard-name, then the `target` `name` is used, /// if it is compatible. Otherwise, a specific name must be provided using - /// [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name). + /// [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::name_if_some`](crate::PadBuilder::name_if_some). /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` /// automatically generated unique name. @@ -224,7 +224,7 @@ impl GhostPad { /// /// If the `name_template` is a wildcard-name, then the `target` `name` is used, /// if it is compatible. Otherwise, a specific name must be provided using - /// [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name). + /// [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::name_if_some`](crate::PadBuilder::name_if_some). /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` /// automatically generated unique name. @@ -710,7 +710,7 @@ impl + IsA> PadBuilder { /// /// If the `name_template` is a wildcard-name, then the `target` `name` is used, /// if it is compatible. Otherwise, a specific name must be provided using - /// [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name). + /// [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::name_if_some`](crate::PadBuilder::name_if_some). /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` /// automatically generated unique name. diff --git a/gstreamer/src/pad.rs b/gstreamer/src/pad.rs index 1eed291ef..75b20b773 100644 --- a/gstreamer/src/pad.rs +++ b/gstreamer/src/pad.rs @@ -1741,6 +1741,7 @@ impl + IsA + glib::object::IsClass> PadBuilder { /// /// This method is convenient when the `name` is provided as an `Option`. /// If the `name` is `None`, this has no effect. + #[deprecated = "use `name_if_some()` instead"] pub fn maybe_name>(self, name: Option) -> Self { if let Some(name) = name { self.name(name) @@ -2104,7 +2105,7 @@ impl + IsA + glib::object::IsClass> PadBuilder { /// Panics if the [`Pad`] was built from a [`PadTemplate`](crate::PadTemplate) /// with a wildcard-name `name_template` (i.e. containing `%u`, `%s` or `%d`) /// and no specific `name` was provided using [`PadBuilder::name`] - /// or [`PadBuilder::maybe_name`], or for [`GhostPad`s](crate::GhostPad), + /// or [`PadBuilder::name_if_some`], or for [`GhostPad`s](crate::GhostPad), /// by defining a `target`. /// /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object` @@ -2665,6 +2666,7 @@ mod tests { } #[test] + #[allow(deprecated)] // maybe_name() is deprecated fn naming() { crate::init().unwrap();