From c5c9c4f1432391f6af9202dd89872e5aae92ca58 Mon Sep 17 00:00:00 2001
From: Jon Pretty <jon.pretty@propensive.com>
Date: Thu, 9 Nov 2017 09:20:20 +0000
Subject: Added Scaladocs

---
 examples/src/main/scala/eq.scala | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

(limited to 'examples/src/main/scala/eq.scala')

diff --git a/examples/src/main/scala/eq.scala b/examples/src/main/scala/eq.scala
index 408f287..cd257f6 100644
--- a/examples/src/main/scala/eq.scala
+++ b/examples/src/main/scala/eq.scala
@@ -5,21 +5,38 @@ import scala.language.higherKinds
 import magnolia._
 import scala.language.experimental.macros
 
+/** typeclass for testing the equality of two values of the same type */
 trait Eq[T] { def equal(value: T, value2: T): Boolean }
 
+/** companion object to [[Eq]] */
 object Eq {
+
+  /** type constructor for the equality typeclass */
   type Typeclass[T] = Eq[T]
+
+  /** defines equality for this case class in terms of equality for all its parameters */
   def combine[T](ctx: CaseClass[Eq, T]): Eq[T] = new Eq[T] {
-    def equal(value1: T, value2: T) =
-      ctx.parameters.forall { param => param.typeclass.equal(param.dereference(value1), param.dereference(value2)) }
+    def equal(value1: T, value2: T) = ctx.parameters.forall { param =>
+      param.typeclass.equal(param.dereference(value1), param.dereference(value2))
+    }
   }
 
+  /** choose which equality subtype to defer to
+   *
+   *  Note that in addition to dispatching based on the type of the first parameter to the `equal`
+   *  method, we check that the second parameter is the same type. */
   def dispatch[T](ctx: SealedTrait[Eq, T]): Eq[T] = new Eq[T] {
-    def equal(value1: T, value2: T): Boolean =
-      ctx.dispatch(value1) { case sub => sub.typeclass.equal(sub.cast(value1), sub.cast(value2)) }
+    def equal(value1: T, value2: T): Boolean = ctx.dispatch(value1) { case sub =>
+      sub.cast.isDefinedAt(value2) && sub.typeclass.equal(sub.cast(value1), sub.cast(value2))
+    }
   }
 
+  /** equality typeclass instance for strings */
   implicit val string: Eq[String] = new Eq[String] { def equal(v1: String, v2: String) = v1 == v2 }
+  
+  /** equality typeclass instance for integers */
   implicit val int: Eq[Int] = new Eq[Int] { def equal(v1: Int, v2: Int) = v1 == v2 }
+  
+  /** binds the Magnolia macro to the `gen` method */
   implicit def gen[T]: Eq[T] = macro Magnolia.gen[T]
 }
-- 
cgit v1.2.3