From c4776becbb9f7aa01d27a5e014ec14adaed462d7 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Fri, 12 Apr 2019 10:54:36 -0700
Subject: [PATCH] Touch up descriptions of `has_type`

---
 crates/backend/src/codegen.rs |  1 +
 src/cast.rs                   | 48 +++++++++++++++++++++--------------
 2 files changed, 30 insertions(+), 19 deletions(-)

diff --git a/crates/backend/src/codegen.rs b/crates/backend/src/codegen.rs
index 6ad6a873..310c5847 100644
--- a/crates/backend/src/codegen.rs
+++ b/crates/backend/src/codegen.rs
@@ -589,6 +589,7 @@ impl ToTokens for ast::ImportType {
         };
 
         let is_type_of = self.is_type_of.as_ref().map(|is_type_of| quote! {
+            #[inline]
             fn is_type_of(val: &JsValue) -> bool {
                 let is_type_of: fn(&JsValue) -> bool = #is_type_of;
                 is_type_of(val)
diff --git a/src/cast.rs b/src/cast.rs
index 6db649cb..f8f0694f 100644
--- a/src/cast.rs
+++ b/src/cast.rs
@@ -16,24 +16,17 @@ pub trait JsCast
 where
     Self: AsRef<JsValue> + Into<JsValue>,
 {
-    /// Test whether this JS value is an instance of the type `T`.
-    ///
-    /// This method performs a dynamic check (at runtime) using the JS
-    /// `instanceof` operator. This method returns `self instanceof T`.
-    ///
-    /// Note that `instanceof` does not work with primitive values or across
-    /// different realms (e.g. iframes). Prefer using `has_type` instead.
-    fn is_instance_of<T>(&self) -> bool
-    where
-        T: JsCast,
-    {
-        T::instanceof(self.as_ref())
-    }
-
     /// Test whether this JS value has a type `T`.
     ///
-    /// Unlike `is_instance_of`, the type can override this to a specialised
-    /// check that works reliably with primitives and across realms.
+    /// This method will dynamically check to see if this JS object can be
+    /// casted to the JS object of type `T`. Usually this uses the `instanceof`
+    /// operator. This also works with primitive types like
+    /// booleans/strings/numbers as well as cross-realm object like `Array`
+    /// which can originate from other iframes.
+    ///
+    /// In general this is intended to be a more robust version of
+    /// `is_instance_of`, but if you want strictly the `instanceof` operator
+    /// it's recommended to use that instead.
     fn has_type<T>(&self) -> bool
     where
         T: JsCast,
@@ -46,7 +39,7 @@ where
     ///
     /// This method will return `Err(self)` if `self.has_type::<T>()`
     /// returns `false`, and otherwise it will return `Ok(T)` manufactured with
-    /// an unchecked cast (verified correct via the `instanceof` operation).
+    /// an unchecked cast (verified correct via the `has_type` operation).
     fn dyn_into<T>(self) -> Result<T, Self>
     where
         T: JsCast,
@@ -63,7 +56,7 @@ where
     ///
     /// This method will return `None` if `self.has_type::<T>()`
     /// returns `false`, and otherwise it will return `Some(&T)` manufactured
-    /// with an unchecked cast (verified correct via the `instanceof` operation).
+    /// with an unchecked cast (verified correct via the `has_type` operation).
     fn dyn_ref<T>(&self) -> Option<&T>
     where
         T: JsCast,
@@ -107,11 +100,28 @@ where
         T::unchecked_from_js_ref(self.as_ref())
     }
 
+    /// Test whether this JS value is an instance of the type `T`.
+    ///
+    /// This method performs a dynamic check (at runtime) using the JS
+    /// `instanceof` operator. This method returns `self instanceof T`.
+    ///
+    /// Note that `instanceof` does not always work with primitive values or
+    /// across different realms (e.g. iframes). If you're not sure whether you
+    /// specifically need only `instanceof` it's recommended to use `has_type`
+    /// instead.
+    fn is_instance_of<T>(&self) -> bool
+    where
+        T: JsCast,
+    {
+        T::instanceof(self.as_ref())
+    }
+
     /// Performs a dynamic `instanceof` check to see whether the `JsValue`
     /// provided is an instance of this type.
     ///
     /// This is intended to be an internal implementation detail, you likely
-    /// won't need to call this.
+    /// won't need to call this. It's generally called through the
+    /// `is_instance_of` method instead.
     fn instanceof(val: &JsValue) -> bool;
 
     /// Performs a dynamic check to see whether the `JsValue` provided