diff --git a/doc/type_traits.qbk b/doc/type_traits.qbk
index 6fa5f65..5461646 100644
--- a/doc/type_traits.qbk
+++ b/doc/type_traits.qbk
@@ -2068,6 +2068,7 @@ expression that evaluates to /true/.]
 [endsect]
 
 [section:is_function is_function]
+   
    template <class T>
    struct is_function : public __tof {};
   
@@ -2107,6 +2108,18 @@ to a member function.]
 
 [:`is_function<T>::value_type` is the type `bool`.]
 
+[tip Don't confuse function-types with pointers to functions:\n\n
+`typedef int f(double);`\n\n
+defines a function type,\n\n
+`f foo;`\n\n
+declares a prototype for a function of type `f`,\n\n
+`f* pf = foo;`\n
+`f& fr = foo;`\n\n
+declares a pointer and a reference to the function `foo`.\n\n
+If you want to detect whether some type is a pointer-to-function then use:\n\n
+`__is_function<__remove_pointer<T>::type>::value && __is_pointer<T>::value`\n\n
+or for pointers to member functions you can just use __is_member_function_pointer directly.]
+
 [endsect]
 
 [section:is_fundamental is_fundamental]
@@ -2355,6 +2368,13 @@ expression that evaluates to /false/.]
 
 [:`is_pointer<T>::value_type` is the type `bool`.]
 
+[important `is_pointer` detects "real" pointer types only, and /not/ smart pointers.
+Users should not specialise `is_pointer` for smart pointer types, as doing so may cause
+Boost (and other third party) code to fail to function correctly.
+Users wanting a trait to detect smart pointers should create their own. 
+However, note that there is no way in general to auto-magically detect smart pointer types, 
+so such a trait would have to be partially specialised for each supported smart pointer type.]
+
 [endsect]
 
 [section:is_polymorphic is_polymorphic]