Add some more context to ADL example

Author: mborland

doc/modules/ROOT/pages/examples.adoc

@@ -103,42 +103,45 @@ Returned Value: 0.25
 
 [#examples_generic_programming]
 == Generic Programming
+
+This example can be found in the `examples/` folder as https://github.com/cppalliance/decimal/blob/develop/examples/adl.cpp[adl.cpp].
+
 [source, c++]
 ----
+#include "test.hpp"
 #include <boost/decimal.hpp>
-#include <limits>
 #include <cmath>
 
-int error_counter = 0;
-
 template <typename T>
-bool float_equal(T lhs, T rhs)
+void sin_identity(T val)
 {
-    using std::fabs;
-    return fabs(lhs - rhs) < std::numeric_limits<T>::epsilon(); // numeric_limits is overloaded for all decimal types
-}
-
-template <typename T>
-void test(T val)
-{
-    using std::sin; // ADL allows builtin and decimal types to both be used
-    if (!float_equal(sin(val), -sin(-val))) // sin(x) == -sin(-x)
-    {
-        ++error_counter;
-    }
+    // ADL allows builtin and decimal types to both be used
+    // Boost.Decimal is not allowed to overload std::sin so it must be provided in its own namespace
+    // You must also include using std::sin to ensure that it is found for the float, double, and long double cases.
+    // It is preferred to have using statements for the functions you intend to use instead of using namespace XXX.
+    using std::sin;
+    using boost::decimal::sin;
+
+    // sin(x) = -sin(-x)
+    // The call here MUST be unqualified, or you will get compiler errors
+    // For example calling std::sin here would not allow any of the decimal types to be used
+    BOOST_DECIMAL_TEST_EQ(sin(val), -sin(-val));
 }
 
 int main()
 {
-    test(-0.5F);
-    test(-0.5);
-    test(-0.5L);
+    // Because of the two using statements in the above function we can now call it with built-in floating point,
+    // or our decimal types as show below
+
+    sin_identity(-0.5F);
+    sin_identity(-0.5);
+    sin_identity(-0.5L);
 
-    test(boost::decimal::decimal32_t{5, -1, true});
-    test(boost::decimal::decimal64_t{5, -1, true});
-    test(boost::decimal::decimal128_t{5, -1, true});
+    sin_identity(boost::decimal::decimal32_t{"-0.5"});
+    sin_identity(boost::decimal::decimal64_t{"-0.5"});
+    sin_identity(boost::decimal::decimal128_t{"-0.5"});
 
-    return error_counter;
+    return boost::decimal::test::report_errors();
 }
 ----
 

examples/adl.cpp

@@ -13,10 +13,15 @@ template <typename T>
 void sin_identity(T val)
 {
     // ADL allows builtin and decimal types to both be used
+    // Boost.Decimal is not allowed to overload std::sin so it must be provided in its own namespace
+    // You must also include using std::sin to ensure that it is found for the float, double, and long double cases.
+    // It is preferred to have using statements for the functions you intend to use instead of using namespace XXX.
     using std::sin;
     using boost::decimal::sin;
 
     // sin(x) = -sin(-x)
+    // The call here MUST be unqualified, or you will get compiler errors
+    // For example calling std::sin here would not allow any of the decimal types to be used
     BOOST_DECIMAL_TEST_EQ(sin(val), -sin(-val));
 }