Imported Upstream version 1.64.0

[platform/upstream/boost.git] / boost / hana / fwd / type.hpp

diff --git a/boost/hana/fwd/type.hpp b/boost/hana/fwd/type.hpp
index d3390cf..c3c220d 100644 (file)
--- a/boost/hana/fwd/type.hpp
+++ b/boost/hana/fwd/type.hpp
@@ -2,7 +2,7 @@
 @file
 Forward declares `boost::hana::type` and related utilities.
 
-@copyright Louis Dionne 2013-2016
+@copyright Louis Dionne 2013-2017
 Distributed under the Boost Software License, Version 1.0.
 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
  */
@@ -37,18 +37,25 @@ BOOST_HANA_NAMESPACE_BEGIN
     //!
     //!
     //! @note
-    //! For subtle reasons having to do with ADL, the actual representation of
-    //! `hana::type` is implementation-defined. In particular, `hana::type`
-    //! may be a dependent type, so one should not attempt to do pattern
-    //! matching on it. However, one can assume that `hana::type` _inherits_
-    //! from `hana::basic_type`, which can be useful when declaring overloaded
-    //! functions:
+    //! For subtle reasons, the actual representation of `hana::type` is
+    //! implementation-defined. In particular, `hana::type` may be a dependent
+    //! type, so one should not attempt to do pattern matching on it. However,
+    //! one can assume that `hana::type` _inherits_ from `hana::basic_type`,
+    //! which can be useful when declaring overloaded functions:
     //! @code
     //!     template <typename T>
     //!     void f(hana::basic_type<T>) {
     //!         // do something with T
     //!     }
     //! @endcode
+    //! The full story is that [ADL][] causes template arguments to be
+    //! instantiated. Hence, if `hana::type` were defined naively, expressions
+    //! like `hana::type<T>{} == hana::type<U>{}` would cause both `T` and `U`
+    //! to be instantiated. This is usually not a problem, except when `T` or
+    //! `U` should not be instantiated. To avoid these instantiations,
+    //! `hana::type` is implemented using some cleverness, and that is
+    //! why the representation is implementation-defined. When that
+    //! behavior is not required, `hana::basic_type` can be used instead.
     //!
     //!
     //! @anchor type_lvalues_and_rvalues
@@ -86,6 +93,8 @@ BOOST_HANA_NAMESPACE_BEGIN
     //! The hash of a type is just that type itself. In other words, `hash`
     //! is the identity function on `hana::type`s.
     //! @include example/type/hashable.cpp
+    //!
+    //! [ADL]: http://en.cppreference.com/w/cpp/language/adl
 #ifdef BOOST_HANA_DOXYGEN_INVOKED
     template <typename T>
     struct type {