From 9be50b3357aecf2561ab71a97891a7e4c90d3450 Mon Sep 17 00:00:00 2001 From: Jason Zaugg Date: Wed, 26 Mar 2014 17:50:37 +0100 Subject: [PATCH] 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 --- build.sbt | 14 ++++++++++---- .../scala/compat/java8/FutureConverters.scala | 15 +++++++-------- .../concurrent/java8/FutureConvertersImpl.scala | 3 ++- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/build.sbt b/build.sbt index cc6e17b..6f0af73 100644 --- a/build.sbt +++ b/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")) ) diff --git a/src/main/scala/scala/compat/java8/FutureConverters.scala b/src/main/scala/scala/compat/java8/FutureConverters.scala index 3508872..e4dbe90 100644 --- a/src/main/scala/scala/compat/java8/FutureConverters.scala +++ b/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. * thenRun will internally call thenRunAsync. * - * @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) } } diff --git a/src/main/scala/scala/concurrent/java8/FutureConvertersImpl.scala b/src/main/scala/scala/concurrent/java8/FutureConvertersImpl.scala index 0c3dd7f..ce9c316 100644 --- a/src/main/scala/scala/concurrent/java8/FutureConvertersImpl.scala +++ b/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) {