From 8a52a343c6cfe275222e9366ccf16dfb718c4750 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Linus=20F=C3=A4rnstrand?= <faern@faern.net>
Date: Mon, 15 Jan 2018 20:42:42 +0100
Subject: [PATCH] Improve documentation and add #[inline]

---
 core-foundation/src/base.rs         | 28 ++++++++++++++++++++++++++++
 core-foundation/src/propertylist.rs | 14 +++++++++++---
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/core-foundation/src/base.rs b/core-foundation/src/base.rs
index 517f6a5..768ba2e 100644
--- a/core-foundation/src/base.rs
+++ b/core-foundation/src/base.rs
@@ -37,6 +37,30 @@ declare_TCFType!{
 }
 
 impl CFType {
+    /// Try to downcast the `CFType` to a subclass. Checking if the instance is the
+    /// correct subclass happens at runtime and `None` is returned if it is not the correct type.
+    /// Works similar to [`Box::downcast`] and [`CFPropertyList::downcast`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use core_foundation::string::CFString;
+    /// # use core_foundation::boolean::CFBoolean;
+    /// # use core_foundation::base::{CFType, TCFType};
+    /// #
+    /// // Create a string.
+    /// let string: CFString = CFString::from_static_string("FooBar");
+    /// // Cast it up to a CFType.
+    /// let cf_type: CFType = string.as_CFType();
+    /// // Cast it down again.
+    /// assert!(cf_type.downcast::<_, CFString>().unwrap().to_string() == "FooBar");
+    /// // Casting it to some other type will yield `None`
+    /// assert!(cf_type.downcast::<_, CFBoolean>().is_none());
+    /// ```
+    ///
+    /// [`Box::downcast`]: https://doc.rust-lang.org/std/boxed/struct.Box.html#method.downcast
+    /// [`CFPropertyList::downcast`]: ../propertylist/struct.CFPropertyList.html#method.downcast
+    #[inline]
     pub fn downcast<Raw, T: TCFType<*const Raw>>(&self) -> Option<T> {
         if self.instance_of::<_, T>() {
             unsafe {
@@ -47,6 +71,10 @@ impl CFType {
         }
     }
 
+    /// Similar to [`downcast`], but consumes self and can thus avoid touching the retain count.
+    ///
+    /// [`downcast`]: #method.downcast
+    #[inline]
     pub fn downcast_into<Raw, T: TCFType<*const Raw>>(self) -> Option<T> {
         if self.instance_of::<_, T>() {
             let reference = self.0 as *const Raw;
diff --git a/core-foundation/src/propertylist.rs b/core-foundation/src/propertylist.rs
index 03d5a40..d98f2ec 100644
--- a/core-foundation/src/propertylist.rs
+++ b/core-foundation/src/propertylist.rs
@@ -66,10 +66,15 @@ pub trait CFPropertyListSubClass<Raw>: TCFType<*const Raw> {
     /// Create an instance of the superclass type [`CFPropertyList`] for this instance.
     ///
     /// [`CFPropertyList`]: struct.CFPropertyList.html
+    #[inline]
     fn to_CFPropertyList(&self) -> CFPropertyList {
         unsafe { CFPropertyList::wrap_under_get_rule(self.as_concrete_TypeRef() as *const c_void) }
     }
 
+    /// Equal to [`to_CFPropertyList`], but consumes self and avoids changing the reference count.
+    ///
+    /// [`to_CFPropertyList`]: #method.to_CFPropertyList
+    #[inline]
     fn into_CFPropertyList(self) -> CFPropertyList
     where Self: Sized
     {
@@ -189,9 +194,9 @@ impl PartialEq for CFPropertyList {
 impl Eq for CFPropertyList {}
 
 impl CFPropertyList {
-    /// Try to downcast the [`CFPropertyList`] to a subclass. Checking if the instance is the correct
-    /// subclass happens at runtime and an error is returned if it is not the correct type.
-    /// Works similar to [`Box::downcast`].
+    /// Try to downcast the [`CFPropertyList`] to a subclass. Checking if the instance is the
+    /// correct subclass happens at runtime and `None` is returned if it is not the correct type.
+    /// Works similar to [`Box::downcast`] and [`CFType::downcast`].
     ///
     /// # Examples
     ///
@@ -209,6 +214,7 @@ impl CFPropertyList {
     ///
     /// [`CFPropertyList`]: struct.CFPropertyList.html
     /// [`Box::downcast`]: https://doc.rust-lang.org/std/boxed/struct.Box.html#method.downcast
+    /// [`CFType::downcast`]: ../base/struct.CFType.html#method.downcast
     pub fn downcast<Raw, T: CFPropertyListSubClass<Raw>>(&self) -> Option<T> {
         if self.instance_of::<_, T>() {
             Some(unsafe { T::wrap_under_get_rule(self.0 as *const Raw) })
@@ -218,6 +224,8 @@ impl CFPropertyList {
     }
 
     /// Similar to [`downcast`], but consumes self and can thus avoid touching the retain count.
+    ///
+    /// [`downcast`]: #method.downcast
     pub fn downcast_into<Raw, T: CFPropertyListSubClass<Raw>>(self) -> Option<T> {
         if self.instance_of::<_, T>() {
             let reference = self.0 as *const Raw;