Merge pull request #1369 from felinira/fina/wrapper-docs

glib::wrapper: Add docs for impls generated by the wrapper macro
gtk-rs · Apr 26, 2024 · 7ba5563 · 7ba5563
2 parents ce3c69e + ab19712
commit 7ba5563
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 0 deletions.
diff --git a/glib/src/boxed.rs b/glib/src/boxed.rs
@@ -32,6 +32,7 @@ macro_rules! glib_boxed_wrapper {
 
     (@generic_impl [$($attr:meta)*] $visibility:vis $name:ident $(<$($generic:ident $(: $bound:tt $(+ $bound2:tt)*)?),+>)?, $ffi_name:ty) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: Boxed type with copy-on-clone semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             inner: $crate::boxed::Boxed<$ffi_name, Self>,
@@ -58,6 +59,7 @@ macro_rules! glib_boxed_wrapper {
         }
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Copies the boxed type with the type-specific copy function."]
             #[inline]
             fn clone(&self) -> Self {
                 Self {

diff --git a/glib/src/boxed_inline.rs b/glib/src/boxed_inline.rs
@@ -10,6 +10,7 @@ macro_rules! glib_boxed_inline_wrapper {
     ([$($attr:meta)*] $visibility:vis $name:ident $(<$($generic:ident $(: $bound:tt $(+ $bound2:tt)*)?),+>)?, $ffi_name:ty
      $(, @type_ $get_type_expr:expr)?) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: Inline allocated boxed type with stack copy semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             pub(crate) inner: $ffi_name,
@@ -18,6 +19,7 @@ macro_rules! glib_boxed_inline_wrapper {
 
         #[allow(clippy::incorrect_clone_impl_on_copy_type)]
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Copies the inline boxed type by value with the type-specific copy function."]
             #[inline]
             fn clone(&self) -> Self {
                 Self {
@@ -43,6 +45,7 @@ macro_rules! glib_boxed_inline_wrapper {
      @copy $copy_arg:ident $copy_expr:expr, @free $free_arg:ident $free_expr:expr
      $(, @type_ $get_type_expr:expr)?) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: Inline allocated boxed type with stack copy semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             pub(crate) inner: $ffi_name,
@@ -52,6 +55,7 @@ macro_rules! glib_boxed_inline_wrapper {
         #[allow(clippy::incorrect_clone_impl_on_copy_type)]
         #[allow(clippy::non_canonical_clone_impl)]
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Copies the inline boxed type by value with the type-specific copy function."]
             #[inline]
             fn clone(&self) -> Self {
                 Self {
@@ -76,13 +80,15 @@ macro_rules! glib_boxed_inline_wrapper {
      @init $init_arg:ident $init_expr:expr, @copy_into $copy_into_arg_dest:ident $copy_into_arg_src:ident $copy_into_expr:expr, @clear $clear_arg:ident $clear_expr:expr
      $(, @type_ $get_type_expr:expr)?) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: Inline allocated boxed type with stack copy semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             pub(crate) inner: $ffi_name,
             $(pub(crate) phantom: std::marker::PhantomData<$($generic),+>,)?
         }
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Copies the inline boxed type by value with the type-specific copy function."]
             #[inline]
             fn clone(&self) -> Self {
                 unsafe {
@@ -117,13 +123,15 @@ macro_rules! glib_boxed_inline_wrapper {
      @init $init_arg:ident $init_expr:expr, @copy_into $copy_into_arg_dest:ident $copy_into_arg_src:ident $copy_into_expr:expr, @clear $clear_arg:ident $clear_expr:expr
      $(, @type_ $get_type_expr:expr)?) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: Inline allocated boxed type with stack copy semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             pub(crate) inner: $ffi_name,
             $(pub(crate) phantom: std::marker::PhantomData<$($generic),+>,)?
         }
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Copies the inline boxed type by value with the type-specific copy function."]
             #[inline]
             fn clone(&self) -> Self {
                 unsafe {

diff --git a/glib/src/object.rs b/glib/src/object.rs
@@ -618,6 +618,7 @@ unsafe impl<T: Send + Sync, P: Send + Sync> Sync for TypedObjectRef<T, P> {}
 macro_rules! glib_object_wrapper {
     (@generic_impl [$($attr:meta)*] $visibility:vis $name:ident $(<$($generic:ident $(: $bound:tt $(+ $bound2:tt)*)?),+>)?, $impl_type:ty, $parent_type:ty, $ffi_name:ty, $ffi_class_name:ty, @type_ $get_type_expr:expr) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: GObject with reference counted clone semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             inner: $crate::object::TypedObjectRef<$impl_type, $parent_type>,
@@ -632,6 +633,7 @@ macro_rules! glib_object_wrapper {
         // are specified, these traits are not required.
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Makes a clone of this shared reference.\n\nThis increments the strong reference count of the object. Dropping the object will decrement it again."]
             #[inline]
             fn clone(&self) -> Self {
                 Self {
@@ -642,6 +644,7 @@ macro_rules! glib_object_wrapper {
         }
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::hash::Hash for $name $(<$($generic),+>)? {
+            #[doc = "Hashes the memory address of this object."]
             #[inline]
             fn hash<H>(&self, state: &mut H)
             where
@@ -652,6 +655,7 @@ macro_rules! glib_object_wrapper {
         }
 
         impl<OT: $crate::object::ObjectType $(, $($generic $(: $bound $(+ $bound2)*)?),+)?> std::cmp::PartialEq<OT> for $name $(<$($generic),+>)? {
+            #[doc = "Equality for two GObjects.\n\nTwo GObjects are equal if their memory addresses are equal."]
             #[inline]
             fn eq(&self, other: &OT) -> bool {
                 std::cmp::PartialEq::eq(&*self.inner, $crate::object::ObjectType::as_object_ref(other))
@@ -661,13 +665,15 @@ macro_rules! glib_object_wrapper {
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::cmp::Eq for $name $(<$($generic),+>)? {}
 
         impl<OT: $crate::object::ObjectType $(, $($generic $(: $bound $(+ $bound2)*)?),+)?> std::cmp::PartialOrd<OT> for $name $(<$($generic),+>)? {
+            #[doc = "Partial comparison for two GObjects.\n\nCompares the memory addresses of the provided objects."]
             #[inline]
             fn partial_cmp(&self, other: &OT) -> Option<std::cmp::Ordering> {
                 std::cmp::PartialOrd::partial_cmp(&*self.inner, $crate::object::ObjectType::as_object_ref(other))
             }
         }
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::cmp::Ord for $name $(<$($generic),+>)? {
+            #[doc = "Comparison for two GObjects.\n\nCompares the memory addresses of the provided objects."]
             #[inline]
             fn cmp(&self, other: &Self) -> std::cmp::Ordering {
                 std::cmp::Ord::cmp(&*self.inner, $crate::object::ObjectType::as_object_ref(other))

diff --git a/glib/src/shared.rs b/glib/src/shared.rs
@@ -30,6 +30,7 @@ macro_rules! glib_shared_wrapper {
     (@generic_impl [$($attr:meta)*] $visibility:vis $name:ident $(<$($generic:ident $(: $bound:tt $(+ $bound2:tt)*)?),+>)?, $ffi_name:ty,
      @ref $ref_arg:ident $ref_expr:expr, @unref $unref_arg:ident $unref_expr:expr) => {
         $(#[$attr])*
+        #[doc = "\n\nGLib type: Shared boxed type with reference counted clone semantics."]
         #[repr(transparent)]
         $visibility struct $name $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? {
             inner: $crate::shared::Shared<$ffi_name, Self>,
@@ -50,6 +51,7 @@ macro_rules! glib_shared_wrapper {
         }
 
         impl $(<$($generic $(: $bound $(+ $bound2)*)?),+>)? std::clone::Clone for $name $(<$($generic),+>)? {
+            #[doc = "Makes a clone of this shared reference.\n\nThis increments the strong reference count of the reference. Dropping the reference will decrement it again."]
             #[inline]
             fn clone(&self) -> Self {
                 Self {