Merge 8f8623c into b4592db

README.md

@@ -13,7 +13,7 @@ A Scala library for handling conversions between types by throwing exceptions or
 ### SBT (Scala 2.11 and 2.12)
 
 ```sbtshell
-"com.nthportal" %% "convert" % "0.1.0"
+"com.nthportal" %% "convert" % "0.1.1"
 ```
 
 ### Maven
@@ -24,7 +24,7 @@ A Scala library for handling conversions between types by throwing exceptions or
 <dependency>
   <groupId>com.nthportal</groupId>
   <artifactId>convert_2.12</artifactId>
-  <version>0.1.0</version>
+  <version>0.1.1</version>
 </dependency>
 ```
 
@@ -34,6 +34,6 @@ A Scala library for handling conversions between types by throwing exceptions or
 <dependency>
   <groupId>com.nthportal</groupId>
   <artifactId>convert_2.11</artifactId>
-  <version>0.1.0</version>
+  <version>0.1.1</version>
 </dependency>
 ```

build.sbt

@@ -3,7 +3,7 @@ name := "convert"
 description := "A Scala library for handling conversions between types by throwing exceptions or returning Options " +
   "containing the results."
 
-val rawVersion = "0.1.0"
+val rawVersion = "0.1.1"
 isSnapshot := false
 version := rawVersion + { if (isSnapshot.value) "-SNAPSHOT" else "" }
 

src/main/scala/com/nthportal/convert/Convert.scala

@@ -25,6 +25,9 @@ import scala.util.control.ControlThrowable
   *     }
   *   }
   * }
+  *
+  * val res1: Boolean = parseBoolean("true")(Convert.Valid)
+  * val res2: Option[Boolean] = parseBoolean("true")(Convert.Any)
   * }}}
   *
   * @define withinConversion This method MUST be called within a conversion
@@ -34,19 +37,26 @@ sealed trait Convert {
 
   import Convert.specTypes
 
+  /** A function which takes the result type of a conversion as input,
+    * and yields the return type of the conversion block.
+    *
+    * For example, if converting a String to a Boolean, this is a function
+    * which takes `Boolean` as input, and yields some type `Result[Boolean]`
+    * (`Boolean` for Convert.Valid, and `Option[Boolean]` for Convert.Any).
+    */
   type Result[T]
 
   /** Performs a conversion.
     *
     * Conversion operations MUST take place within this block
-    * (a `conversion` block).
+    * (a 'conversion block').
     *
     * @example
-    * {{{*
+    * {{{
     * conversion {
-    *   // Do conversion here
-    *   // - fail if something goes wrong
-    *   // - return a result
+    *   val res = ??? // do conversion
+    *   if (cond) fail(new IllegalArgumentException("invalid input")) // fail if something goes wrong
+    *   res // return a result
     * }
     * }}}
     *
@@ -61,7 +71,6 @@ sealed trait Convert {
     * $withinConversion
     *
     * @param ex an exception to throw, if this Convert throws exceptions
-    * @return
     */
   def fail(ex: => Exception): Nothing
 
@@ -149,8 +158,22 @@ object Convert {
 
     override def conversion[@specialized(specTypes) T](res: => T): T = res
 
+    /** Throws the specified exception.
+      *
+      * $withinConversion
+      *
+      * @param ex the exception to throw
+      */
     override def fail(ex: => Exception): Nothing = throw ex
 
+    /** Returns the result of another conversion.
+      *
+      * $withinConversion
+      *
+      * @param result the result of another conversion
+      * @tparam T the type of the result
+      * @return the result of the other conversion
+      */
     override def unwrap[@specialized(specTypes) T](result: T): T = result
   }
 
@@ -170,8 +193,25 @@ object Convert {
       }
     }
 
+    /** Terminates the enclosing conversion block with [[scala.None None]].
+      *
+      * $withinConversion
+      *
+      * @param ex ignored
+      */
     override def fail(ex: => Exception): Nothing = throw FailControl
 
+    /** Unwraps the result of another conversion (an [[scala.Option Option]]).
+      *
+      * If the result was [[scala.None None]], this terminates the enclosing
+      * conversion block with None; otherwise, it returns the value of the Option.
+      *
+      * $withinConversion
+      *
+      * @param result the result of another conversion
+      * @tparam T the type of the `Option[T]`
+      * @return the result of the other conversion, not wrapped in an Option
+      */
     override def unwrap[@specialized(specTypes) T](result: Option[T]): T = result match {
       case Some(t) => t
       case None => throw FailControl