Workaround bugs in doc tools

Both Scaladoc and genjavadoc take exception to this project.

  - raw types in the generated mixin composition befuddle
    scaladoc (lodged as https://issues.scala-lang.org/browse/SI-8449)
  - implicit classes seem to mess up genjavadoc
  - as do private[pack] classes

Finally, I had to remove parameter documentation from the
`toJava` and `toScala` decorators, as the reference parameter
was the argument to the implicit conversion, not to the documented
method.

All said an done, we end up with:

 https://dl.dropboxusercontent.com/u/106552/genjavadoc-scala-java8-compat/genjavadoc-api/index.html

Author: retronym

build.sbt

@@ -64,14 +64,20 @@ initialize := {
 
 lazy val JavaDoc = config("genjavadoc") extend Compile
 
+sources in (Compile, doc) := {
+  val orig = (sources in (Compile, doc)).value
+  orig.filterNot(_.getName.endsWith(".java")) // raw types not cooked by scaladoc: https://issues.scala-lang.org/browse/SI-8449
+}
+
 inConfig(JavaDoc)(Defaults.configSettings) ++ Seq(
   packageDoc in Compile <<= packageDoc in JavaDoc,
-  sources in JavaDoc <<= (target, compile in Compile, sources in Compile) map ((t, c, s) =>
-    (t / "java" ** "*.java").get ++ s.filter(_.getName.endsWith(".java"))
-  ),
+  sources in JavaDoc <<= (target, compile in Compile, sources in Compile) map {(t, c, s) =>
+    val allJavaSources = (t / "java" ** "*.java").get ++ s.filter(_.getName.endsWith(".java"))
+    allJavaSources.filterNot(_.getName.contains("FuturesConvertersImpl.java")) // this file triggers bugs in genjavadoc
+  },
   javacOptions in JavaDoc := Seq(),
   artifactName in packageDoc in JavaDoc := ((sv, mod, art) => "" + mod.name + "_" + sv.binary + "-" + mod.revision + "-javadoc.jar"),
-  libraryDependencies += compilerPlugin("com.typesafe.genjavadoc" % "genjavadoc-plugin_2.10.4" % "0.5"),
+  libraryDependencies += compilerPlugin("com.typesafe.genjavadoc" %% "genjavadoc-plugin" % "0.5" cross CrossVersion.full),
   scalacOptions in Compile <+= target map (t => "-P:genjavadoc:out=" + (t / "java"))
 )
 

src/main/scala/scala/compat/java8/FutureConverters.scala

@@ -155,7 +155,8 @@ object FutureConverters {
    */
   def failedPromise[T](ex: Throwable): Promise[T] = Promise.failed(ex)
 
-  implicit class futureToCompletionStage[T](val f: Future[T]) extends AnyVal {
+  implicit def FutureOps[T](f: Future[T]): FutureOps[T] = new FutureOps[T](f)
+  final class FutureOps[T](val __self: Future[T]) extends AnyVal {
     /**
      * Returns a CompletionStage that will be completed with the same value or
      * exception as the given Scala Future when that completes. Since the Future is a read-only
@@ -166,25 +167,23 @@ object FutureConverters {
      * transformations to their asynchronous counterparts, i.e.
      * <code>thenRun</code> will internally call <code>thenRunAsync</code>.
      *
-     * @param f The Scala Future which may eventually supply the completion for
-     * the returned CompletionStage
      * @return a CompletionStage that runs all callbacks asynchronously and does
      * not support the CompletableFuture interface
      */
-    def toJava: CompletionStage[T] = FutureConverters.toJava(f)
+    def toJava: CompletionStage[T] = FutureConverters.toJava(__self)
   }
 
-  implicit class completionStageToFuture[T](val cs: CompletionStage[T]) extends AnyVal {
+  implicit def CompletionStageOps[T](cs: CompletionStage[T]): CompletionStageOps[T] = new CompletionStageOps(cs)
+
+  final class CompletionStageOps[T](val __self: CompletionStage[T]) extends AnyVal {
     /**
      * Returns a Scala Future that will be completed with the same value or
      * exception as the given CompletionStage when that completes. Transformations
      * of the returned Future are executed asynchronously as specified by the
      * ExecutionContext that is given to the combinator methods.
      *
-     * @param cs The CompletionStage which may eventually supply the completion
-     * for the returned Scala Future
      * @return a Scala Future that represents the CompletionStage's completion
      */
-    def toScala: Future[T] = FutureConverters.toScala(cs)
+    def toScala: Future[T] = FutureConverters.toScala(__self)
   }
 }

src/main/scala/scala/concurrent/java8/FutureConvertersImpl.scala

@@ -7,7 +7,8 @@ import java.util.concurrent.{ CompletionStage, Executor, ExecutorService, Comple
 import scala.util.{ Try, Success, Failure }
 import java.util.function.{ BiConsumer, Function ⇒ JF, Consumer, BiFunction }
 
-private[scala] object FuturesConvertersImpl {
+// TODO: make thie private[scala] when genjavadoc allows for that.
+object FuturesConvertersImpl {
   def InternalCallbackExecutor = Future.InternalCallbackExecutor
 
   class CF[T] extends CompletableFuture[T] with (Try[T] => Unit) {