Merge pull request #1005 from MathieuDuponchelle/downcast-docs

object: improve downcasting docs

Author: sdroege

glib/src/object.rs

@@ -122,10 +122,9 @@ pub trait Cast: ObjectType {
     /// Returns `Ok(T)` if the object is an instance of `T` and `Err(self)`
     /// otherwise.
     ///
-    /// *NOTE*: This statically checks at compile-time if casting is possible. It is not always
-    /// known at compile-time, whether a specific object implements an interface or not, in which case
-    /// `upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which
-    /// is checking the types at runtime.
+    /// *NOTE*: This will check at compile-time if `T` is lower down the
+    /// inheritance tree of `Self`, but also check at runtime if downcasting
+    /// is indeed possible.
     ///
     /// # Example
     ///
@@ -137,7 +136,7 @@ pub trait Cast: ObjectType {
     #[inline]
     fn downcast<T: ObjectType>(self) -> Result<T, Self>
     where
-        Self: CanDowncast<T>,
+        Self: MayDowncastTo<T>,
     {
         if self.is::<T>() {
             Ok(unsafe { self.unsafe_cast() })
@@ -152,10 +151,9 @@ pub trait Cast: ObjectType {
     /// Returns `Some(T)` if the object is an instance of `T` and `None`
     /// otherwise.
     ///
-    /// *NOTE*: This statically checks at compile-time if casting is possible. It is not always
-    /// known at compile-time, whether a specific object implements an interface or not, in which case
-    /// `upcast` would fail to compile. `dynamic_cast` can be used in these circumstances, which
-    /// is checking the types at runtime.
+    /// *NOTE*: This will check at compile-time if `T` is lower down the
+    /// inheritance tree of `Self`, but also check at runtime if downcasting
+    /// is indeed possible.
     ///
     /// # Example
     ///
@@ -167,7 +165,7 @@ pub trait Cast: ObjectType {
     #[inline]
     fn downcast_ref<T: ObjectType>(&self) -> Option<&T>
     where
-        Self: CanDowncast<T>,
+        Self: MayDowncastTo<T>,
     {
         if self.is::<T>() {
             Some(unsafe { self.unsafe_cast_ref() })
@@ -179,7 +177,9 @@ pub trait Cast: ObjectType {
     // rustdoc-stripper-ignore-next
     /// Tries to cast to an object of type `T`. This handles upcasting, downcasting
     /// and casting between interface and interface implementors. All checks are performed at
-    /// runtime, while `downcast` and `upcast` will do many checks at compile-time already.
+    /// runtime, while `upcast` will do many checks at compile-time already. `downcast` will
+    /// perform the same checks at runtime as `dynamic_cast`, but will also ensure some amount of
+    /// compile-time safety.
     ///
     /// It is not always known at compile-time, whether a specific object implements an interface or
     /// not, and checking has to be performed at runtime.
@@ -303,10 +303,10 @@ pub trait CastNone: Sized {
     type Inner;
     fn and_downcast<T: ObjectType>(self) -> Option<T>
     where
-        Self::Inner: CanDowncast<T>;
+        Self::Inner: MayDowncastTo<T>;
     fn and_downcast_ref<T: ObjectType>(&self) -> Option<&T>
     where
-        Self::Inner: CanDowncast<T>;
+        Self::Inner: MayDowncastTo<T>;
     fn and_upcast<T: ObjectType>(self) -> Option<T>
     where
         Self::Inner: IsA<T>;
@@ -322,15 +322,15 @@ impl<I: ObjectType + Sized> CastNone for Option<I> {
     #[inline]
     fn and_downcast<T: ObjectType>(self) -> Option<T>
     where
-        Self::Inner: CanDowncast<T>,
+        Self::Inner: MayDowncastTo<T>,
     {
         self.and_then(|i| i.downcast().ok())
     }
 
     #[inline]
     fn and_downcast_ref<T: ObjectType>(&self) -> Option<&T>
     where
-        Self::Inner: CanDowncast<T>,
+        Self::Inner: MayDowncastTo<T>,
     {
         self.as_ref().and_then(|i| i.downcast_ref())
     }
@@ -365,9 +365,9 @@ impl<I: ObjectType + Sized> CastNone for Option<I> {
 
 // rustdoc-stripper-ignore-next
 /// Marker trait for the statically known possibility of downcasting from `Self` to `T`.
-pub trait CanDowncast<T> {}
+pub trait MayDowncastTo<T> {}
 
-impl<Super: IsA<Super>, Sub: IsA<Super>> CanDowncast<Sub> for Super {}
+impl<Super: IsA<Super>, Sub: IsA<Super>> MayDowncastTo<Sub> for Super {}
 
 // Manual implementation of glib_shared_wrapper! because of special cases
 #[repr(transparent)]