Added Scaladocs

5 files changed, 63 insertions, 5 deletions

diff --git a/build.sbt b/build.sbt
index 5353b03..616fc48 100644
--- a/build.sbt
+++ b/build.sbt
@@ -64,7 +64,7 @@ lazy val buildSettings = Seq(
   organization := "com.propensive",
   scalaVersion := "2.12.4",
   name := "magnolia",
-  version := "0.2.0",
+  version := "0.4.0",
   scalacOptions ++= Seq("-deprecation", "-feature", "-Ywarn-value-discard", "-Ywarn-dead-code", "-Ywarn-nullary-unit", "-Ywarn-numeric-widen", "-Ywarn-inaccessible", "-Ywarn-adapted-args"),
   crossScalaVersions := Seq("2.10.6", "2.11.11", "2.12.2"),
   scmInfo := Some(ScmInfo(url("https://github.com/propensive/magnolia"),
diff --git a/examples/src/main/scala/decode.scala b/examples/src/main/scala/decode.scala
index a5d1d67..eca56d2 100644
--- a/examples/src/main/scala/decode.scala
+++ b/examples/src/main/scala/decode.scala
@@ -6,16 +6,25 @@ import scala.language.higherKinds
 import magnolia._
 import scala.language.experimental.macros
 
+/** very basic decoder for converting strings to other types */
 trait Decoder[T] { def decode(str: String): T }
 
+/** derivation object (and companion object) for [[Derivation]] instances */
 object Decoder {
   
+  /** decodes strings */
   implicit val string: Decoder[String] = new Decoder[String] { def decode(str: String): String = str }
+
+  /** decodes ints */
   implicit val int: Decoder[Int] = new Decoder[Int] { def decode(str: String): Int = str.toInt }
+
+  /** binds the Magnolia macro to this derivation object */
   implicit def gen[T]: Decoder[T] = macro Magnolia.gen[T]
 
+  /** type constructor for new instances of the typeclass */
   type Typeclass[T] = Decoder[T]
   
+  /** defines how new [[Decoder]]s for case classes should be constructed */
   def combine[T](ctx: CaseClass[Decoder, T]): Decoder[T] = new Decoder[T] {
     def decode(value: String) = {
       val (name, values) = parse(value)
@@ -23,6 +32,7 @@ object Decoder {
     }
   }
 
+  /** defines how to choose which subtype of the sealed trait to use for decoding */
   def dispatch[T](ctx: SealedTrait[Decoder, T]): Decoder[T] = new Decoder[T] {
     def decode(param: String) = {
       val (name, values) = parse(param)
@@ -31,6 +41,7 @@ object Decoder {
     }
   }
 
+  /** very simple extractor for grabbing an entire parameter value, assuming matching parentheses */
   private def parse(value: String): (String, Map[String, String]) = {
     val end = value.indexOf('(')
     val name = value.substring(0, end)
diff --git a/examples/src/main/scala/default.scala b/examples/src/main/scala/default.scala
index 55b0753..ea881df 100644
--- a/examples/src/main/scala/default.scala
+++ b/examples/src/main/scala/default.scala
@@ -6,19 +6,31 @@ import scala.language.higherKinds
 import magnolia._
 import scala.language.experimental.macros
 
+/** typeclass for providing a default value for a particular type */
 trait Default[T] { def default: T }
 
+/** companion object and derivation object for [[Default]] */
 object Default {
+
   type Typeclass[T] = Default[T]
+  
+  /** constructs a default for each parameter, using the constructor default (if provided),
+   *  otherwise using a typeclass-provided default */
   def combine[T](ctx: CaseClass[Default, T]): Default[T] = new Default[T] {
     def default = ctx.construct { param => param.default.getOrElse(param.typeclass.default) }
   }
 
+  /** chooses which subtype to delegate to */
   def dispatch[T](ctx: SealedTrait[Default, T])(): Default[T] = new Default[T] {
     def default: T = ctx.subtypes.head.typeclass.default
   }
 
+  /** default value for a string; the empty string */
   implicit val string: Default[String] = new Default[String] { def default = "" }
+
+  /** default value for ints; 0 */
   implicit val int: Default[Int] = new Default[Int] { def default = 0 }
+
+  /** generates default instances of [[Default]] for case classes and sealed traits */
   implicit def gen[T]: Default[T] = macro Magnolia.gen[T]
 }
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]
 }
diff --git a/examples/src/main/scala/show.scala b/examples/src/main/scala/show.scala
index 4594bff..9da507c 100644
--- a/examples/src/main/scala/show.scala
+++ b/examples/src/main/scala/show.scala
@@ -6,21 +6,39 @@ import scala.language.higherKinds
 import magnolia._
 import scala.language.experimental.macros
 
+/** shows one type as another, often as a string
+ *
+ *  Note that this is a more general form of `Show` than is usual, as it permits the return type to
+ *  be something other than [[String]]. */
 trait Show[Out, T] { def show(value: T): Out }
 
+/** companion object to [[Show]] */
 object Show {
+
+  /** the type constructor for new [[Show]] instances
+   *
+   *  The first parameter is fixed as [[String]], and the second parameter varies generically. */
   type Typeclass[T] = Show[String, T]
+
+  /** creates a new [[Show]] instance by labelling and joining (with `mkString`) the result of
+   *  showing each parameter, and prefixing it with the class name */
   def combine[T](ctx: CaseClass[Typeclass, T]): Show[String, T] = new Show[String, T] {
     def show(value: T) = ctx.parameters.map { param =>
       s"${param.label}=${param.typeclass.show(param.dereference(value))}"
     }.mkString(s"${ctx.typeName.split("\\.").last}(", ",", ")")
   }
 
+  /** choose which typeclass to use based on the subtype of the sealed trait */
   def dispatch[T](ctx: SealedTrait[Typeclass, T]): Show[String, T] = new Show[String, T] {
     def show(value: T): String = ctx.dispatch(value) { sub => sub.typeclass.show(sub.cast(value)) }
   }
 
+  /** show typeclass for strings */
   implicit val string: Show[String, String] = new Show[String, String] { def show(s: String): String = s }
+  
+  /** show typeclass for integers */
   implicit val int: Show[String, Int] = new Show[String, Int] { def show(s: Int): String = s.toString }
+  
+  /** bind the Magnolia macro to this derivation object */
   implicit def gen[T]: Show[String, T] = macro Magnolia.gen[T]
 }