[difference] Document separately for map and set

Closes #341

include/boost/hana/fwd/difference.hpp

@@ -15,50 +15,18 @@ Distributed under the Boost Software License, Version 1.0.
 
 
 BOOST_HANA_NAMESPACE_BEGIN
-    //! Returns the set-theoretic difference of two sets.
-    //! @relates hana::set
-    //!
-    //! Given two sets `xs` and `ys`, `difference(xs, ys)` is a new set
-    //! containing all the elements of `xs` that are _not_ contained in `ys`.
-    //! For any object `x`, the following holds:
-    //! @code
-    //!     x ^in^ difference(xs, ys) if and only if x ^in^ xs && !(x ^in^ ys)
-    //! @endcode
-    //!
-    //!
-    //! @note
-    //! This operation is not commutative, i.e. `difference(xs, ys)` is not
-    //! necessarily the same as `difference(ys, xs)`. Indeed, consider the
-    //! case where `xs` is empty and `ys` isn't. Then, `difference(xs, ys)`
-    //! is empty but `difference(ys, xs)` is equal to `ys`. For the symmetric
-    //! version of this operation, see `symmetric_difference`.
-    //!
-    //!
-    //! @param xs
-    //! A set to remove values from.
-    //!
-    //! @param ys
-    //! The set whose values are removed from `xs`.
-    //!
-    //!
-    //! Example
-    //! -------
-    //! @include example/difference.cpp
-#ifdef BOOST_HANA_DOXYGEN_INVOKED
-    constexpr auto difference = [](auto&& xs, auto&& ys) {
-        return tag-dispatched;
-    };
-#else
+    // Note: This function is documented per datatype/concept only.
+	//! @cond
     template <typename S, typename = void>
     struct difference_impl : difference_impl<S, when<true>> { };
+    //! @cond
 
     struct difference_t {
         template <typename Xs, typename Ys>
-        constexpr auto operator()(Xs&& xs, Ys&& ys) const;
+        constexpr auto operator()(Xs&&, Ys&&) const;
     };
 
     constexpr difference_t difference{};
-#endif
 BOOST_HANA_NAMESPACE_END
 
 #endif // !BOOST_HANA_FWD_DIFFERENCE_HPP

include/boost/hana/fwd/map.hpp

@@ -315,6 +315,36 @@ BOOST_HANA_NAMESPACE_BEGIN
     };
 #endif
 
+    //! Returns the difference of two maps.
+    //! @relates hana::map
+    //!
+    //! Given two maps `xs` and `ys`, `difference(xs, ys)` is a new map
+    //! containing exactly those (key, value) pairs from xs, for which key
+    //! is not present in `keys(ys)`.
+    //! In other words, the following holds for any object `pair(k, v)`:
+    //! @code
+    //!     pair(k, v) ^in^ difference(xs, ys) if and only if (k, v) ^in^ xs && k ^not in^ ys.keys()
+    //! @endcode
+    //!
+    //!
+    //! @note
+    //! This function is not commutative, i.e. `difference(xs, ys)` is
+    //! not necessarily same as `difference(ys, xs)`.
+    //!
+    //!
+    //! @param xs, ys
+    //! Two maps to find difference.
+    //!
+    //!
+    //! Example
+    //! -------
+    //! @include example/map/intersection.cpp
+#ifdef BOOST_HANA_DOXYGEN_INVOKED
+    constexpr auto difference = [](auto&& xs, auto&& ys) {
+        return tag-dispatched;
+    };
+#endif
+
 BOOST_HANA_NAMESPACE_END
 
 #endif // !BOOST_HANA_FWD_MAP_HPP

include/boost/hana/fwd/set.hpp

@@ -209,7 +209,8 @@ BOOST_HANA_NAMESPACE_BEGIN
     //!
     //! Given two sets `xs` and `ys`, `intersection(xs, ys)` is a new set
     //! containing exactly those elements that are present both in `xs` and
-    //! in `ys`. In other words, the following holds for any object `x`:
+    //! in `ys`.
+    //! In other words, the following holds for any object `x`:
     //! @code
     //!     x ^in^ intersection(xs, ys) if and only if x ^in^ xs && x ^in^ ys
     //! @endcode
@@ -232,4 +233,34 @@ BOOST_HANA_NAMESPACE_BEGIN
     constexpr auto to_set = to<set_tag>;
 BOOST_HANA_NAMESPACE_END
 
+	//! Returns the difference of two sets.
+	//! @relates hana::set
+	//!
+	//! Given two sets `xs` and `ys`, `difference(xs, ys)` is a
+	//! new set containing exactly those elements from xs,
+	//! which are not ys.
+	//! In other words, the following holds for any object `x`:
+	//! @code
+	//!     x ^in^ difference(xs, ys) if and only if x ^in^ xs && x ^not in^ ys.keys()
+	//! @endcode
+	//!
+	//!
+	//! @note
+	//! This function is not commutative, i.e. `difference(xs, ys)` is
+	//! not necessarily same as `difference(ys, xs)`.
+	//!
+	//!
+	//! @param xs, ys
+	//! Two sets to find difference.
+	//!
+	//!
+	//! Example
+	//! -------
+	//! @include example/set/intersection.cpp
+#ifdef BOOST_HANA_DOXYGEN_INVOKED
+	constexpr auto difference = [](auto&& xs, auto&& ys) {
+		return tag-dispatched;
+};
+#endif
+
 #endif // !BOOST_HANA_FWD_SET_HPP