Merge branch 'ghost_pad-automatic-name' into 'main'

Pad: allow building a Pad with an automatically generated name

See merge request gstreamer/gstreamer-rs!1428

gstreamer/src/ghost_pad.rs

@@ -56,6 +56,8 @@ impl GhostPad {
     // rustdoc-stripper-ignore-next
     /// Creates a new [`GhostPad`] with an automatically generated name.
     ///
+    /// The [`Pad`] will be assigned the usual `gst::Object` generated unique name.
+    ///
     /// Use [`GhostPad::builder_from_template()`] to get a [`PadBuilder`](crate::PadBuilder)
     /// and define options.
     #[doc(alias = "gst_ghost_pad_new_no_target")]
@@ -65,10 +67,7 @@ impl GhostPad {
     }
 
     // rustdoc-stripper-ignore-next
-    /// Creates a [`PadBuilder`](crate::PadBuilder) for a [`PadBuilder`] with an automatically generated name.
-    ///
-    /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name)
-    /// to specify a different name.
+    /// Creates a [`PadBuilder`](crate::PadBuilder) with the specified [`PadDirection`](crate::PadDirection).
     #[doc(alias = "gst_ghost_pad_new_no_target")]
     pub fn builder(direction: crate::PadDirection) -> PadBuilder<Self> {
         skip_assert_initialized!();
@@ -82,15 +81,15 @@ 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`.
     ///
-    /// # Panics
-    ///
-    /// Panics if the `name_template` is a wildcard-name.
-    ///
     /// Use [`GhostPad::builder_from_template()`] to get a [`PadBuilder`](crate::PadBuilder)
     /// and define options.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the `name_template` is a wildcard-name.
     #[doc(alias = "gst_ghost_pad_new_no_target_from_static_template")]
     pub fn from_static_template(templ: &StaticPadTemplate) -> Self {
         skip_assert_initialized!();
@@ -107,8 +106,8 @@ impl GhostPad {
     /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name)
     /// to specify a different name.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_ghost_pad_new_no_target_from_static_template")]
     pub fn builder_from_static_template(templ: &StaticPadTemplate) -> PadBuilder<Self> {
         skip_assert_initialized!();
@@ -122,15 +121,15 @@ 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`.
     ///
-    /// # Panics
-    ///
-    /// Panics if the `name_template` is a wildcard-name.
-    ///
     /// Use [`GhostPad::builder_from_template()`] to get a [`PadBuilder`](crate::PadBuilder)
     /// and define options.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the `name_template` is a wildcard-name.
     #[doc(alias = "gst_ghost_pad_new_no_target_from_template")]
     pub fn from_template(templ: &crate::PadTemplate) -> Self {
         skip_assert_initialized!();
@@ -147,8 +146,8 @@ impl GhostPad {
     /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name)
     /// to specify a different name.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_ghost_pad_new_no_target_from_template")]
     pub fn builder_from_template(templ: &crate::PadTemplate) -> PadBuilder<Self> {
         skip_assert_initialized!();
@@ -163,8 +162,8 @@ impl GhostPad {
     /// Use [`GhostPad::builder_with_target()`] to get a [`PadBuilder`](crate::PadBuilder)
     /// and define options.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_ghost_pad_new")]
     pub fn with_target<P: IsA<Pad> + IsA<crate::Object>>(
         target: &P,
@@ -181,8 +180,8 @@ impl GhostPad {
     /// Use [`PadBuilder::name`](crate::PadBuilder::name) or [`PadBuilder::maybe_name`](crate::PadBuilder::maybe_name)
     /// to specify a different name.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_ghost_pad_new_no_target_from_template")]
     pub fn builder_with_target<P: IsA<Pad> + IsA<crate::Object>>(
         target: &P,
@@ -204,8 +203,8 @@ impl GhostPad {
     /// 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).
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_ghost_pad_new_from_template")]
     pub fn from_template_with_target<P: IsA<Pad> + IsA<crate::Object>>(
         templ: &crate::PadTemplate,
@@ -227,8 +226,8 @@ impl GhostPad {
     /// 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).
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_ghost_pad_new_from_template")]
     pub fn builder_from_template_with_target<P: IsA<Pad> + IsA<crate::Object>>(
         templ: &crate::PadTemplate,
@@ -713,8 +712,8 @@ impl<T: IsA<GhostPad> + IsA<Pad>> PadBuilder<T> {
     /// 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).
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     pub fn with_target<P: IsA<Pad> + IsA<crate::Object>>(
         mut self,
         target: &P,

gstreamer/src/pad.rs

@@ -1428,7 +1428,7 @@ impl Pad {
     // rustdoc-stripper-ignore-next
     /// Creates a new [`Pad`] with the specified [`PadDirection`](crate::PadDirection).
     ///
-    /// An automatically generated name will be assigned.
+    /// The [`Pad`] will be assigned the usual `gst::Object` generated unique name.
     ///
     /// Use [`Pad::builder()`] to get a [`PadBuilder`] and define options.
     #[doc(alias = "gst_pad_new")]
@@ -1439,8 +1439,6 @@ impl Pad {
 
     // rustdoc-stripper-ignore-next
     /// Creates a [`PadBuilder`] with the specified [`PadDirection`](crate::PadDirection).
-    ///
-    /// An automatically generated name will be assigned.
     #[doc(alias = "gst_pad_new")]
     pub fn builder(direction: crate::PadDirection) -> PadBuilder<Self> {
         skip_assert_initialized!();
@@ -1454,14 +1452,14 @@ impl Pad {
     /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`,
     /// the `Pad` will automatically be named after the `name_template`.
     ///
+    /// Use [`Pad::builder_from_static_template()`] to get a [`PadBuilder`] and define options.
+    ///
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
+    ///
     /// # Panics
     ///
     /// Panics if the `name_template` is a wildcard-name.
-    ///
-    /// Use [`Pad::builder_from_static_template()`] to get a [`PadBuilder`] and define options.
-    ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
     #[doc(alias = "gst_pad_new_from_static_template")]
     pub fn from_static_template(templ: &StaticPadTemplate) -> Self {
         skip_assert_initialized!();
@@ -1475,8 +1473,8 @@ impl Pad {
     /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`,
     /// the `Pad` will automatically be named after the `name_template`.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_pad_new_from_static_template")]
     pub fn builder_from_static_template(templ: &StaticPadTemplate) -> PadBuilder<Self> {
         skip_assert_initialized!();
@@ -1490,11 +1488,11 @@ impl Pad {
     /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`,
     /// the `Pad` will automatically be named after the `name_template`.
     ///
+    /// Use [`Pad::builder_from_template()`] to get a [`PadBuilder`] and define options.
+    ///
     /// # Panics
     ///
     /// Panics if the `name_template` is a wildcard-name.
-    ///
-    /// Use [`Pad::builder_from_template()`] to get a [`PadBuilder`] and define options.
     #[doc(alias = "gst_pad_new_from_template")]
     pub fn from_template(templ: &crate::PadTemplate) -> Self {
         skip_assert_initialized!();
@@ -1508,8 +1506,8 @@ impl Pad {
     /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`,
     /// the `Pad` will automatically be named after the `name_template`.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[doc(alias = "gst_pad_new_from_template")]
     pub fn builder_from_template(templ: &crate::PadTemplate) -> PadBuilder<Self> {
         skip_assert_initialized!();
@@ -1579,9 +1577,6 @@ pub struct PadBuilder<T> {
 impl<T: IsA<Pad> + IsA<glib::Object> + glib::object::IsClass> PadBuilder<T> {
     // rustdoc-stripper-ignore-next
     /// Creates a `PadBuilder` with the specified [`PadDirection`](crate::PadDirection).
-    ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
     pub fn new(direction: crate::PadDirection) -> Self {
         assert_initialized_main_thread!();
 
@@ -1611,8 +1606,8 @@ impl<T: IsA<Pad> + IsA<glib::Object> + glib::object::IsClass> PadBuilder<T> {
     /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`,
     /// the `Pad` will automatically be named after the `name_template`.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     pub fn from_static_template(templ: &StaticPadTemplate) -> Self {
         skip_assert_initialized!();
 
@@ -1627,8 +1622,8 @@ impl<T: IsA<Pad> + IsA<glib::Object> + glib::object::IsClass> PadBuilder<T> {
     /// i.e. if it's not a wildcard-name containing `%u`, `%s` or `%d`,
     /// the `Pad` will automatically be named after the `name_template`.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     pub fn from_template(templ: &crate::PadTemplate) -> Self {
         assert_initialized_main_thread!();
 
@@ -1675,7 +1670,7 @@ impl<T: IsA<Pad> + IsA<glib::Object> + glib::object::IsClass> PadBuilder<T> {
     }
 
     // rustdoc-stripper-ignore-next
-    /// Uses the automatically generated unique name.
+    /// Uses the `gst::Object` generated unique name.
     pub fn generated_name(mut self) -> Self {
         self.name = PadBuilderName::KeepGenerated;
         self
@@ -2060,8 +2055,8 @@ impl<T: IsA<Pad> + IsA<glib::Object> + glib::object::IsClass> PadBuilder<T> {
     /// or [`PadBuilder::maybe_name`], or for [`GhostPad`s](crate::GhostPad),
     /// by defining a `target`.
     ///
-    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the automatically
-    /// generated name.
+    /// Use [`generated_name()`](crate::PadBuilder::generated_name`) to keep the `gst::Object`
+    /// automatically generated unique name.
     #[must_use = "Building the pad without using it has no effect"]
     #[track_caller]
     pub fn build(self) -> T {