diff --git a/README.md b/README.md index bd22144..3b63754 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,36 @@ GenJavadoc can also be integrated into a Maven build (inspired by [this answer o ~~~ +You can integrate genjavadoc with gradle build: + +~~~ groovy +apply plugin: 'scala' + +configurations { + scalaCompilerPlugin +} + +dependencies { + // ... + scalaCompilerPlugin "com.typesafe.genjavadoc:genjavadoc-plugin_${scalaFullVersion}:0.13" + +} + +tasks.withType(ScalaCompile) { + scalaCompileOptions.with { + additionalParameters = [ + "-Xplugin:" + configurations.scalaCompilerPlugin.asPath, + "-P:genjavadoc:out=$buildDir/generated/java".toString() + ] + } +} + +tasks.withType(Javadoc) { + dependsOn("compileScala") + source = [sourceSets.main.allJava, "$buildDir/generated/java"] +} +~~~ + ### Translation of Scaladoc comments Comments found within the Scala sources are transferred to the corresponding Java sources including some modifications. These are necessary since Scaladoc supports different mark-up elements than Javadoc. The modifications are: diff --git a/plugin/src/main/scala/com/typesafe/genjavadoc/AST.scala b/plugin/src/main/scala/com/typesafe/genjavadoc/AST.scala index d5bd7f4..ef46f53 100644 --- a/plugin/src/main/scala/com/typesafe/genjavadoc/AST.scala +++ b/plugin/src/main/scala/com/typesafe/genjavadoc/AST.scala @@ -28,9 +28,24 @@ trait AST { this: TransformCake => static: Boolean, var firstConstructor: Boolean) extends Templ { - def sig = pattern(name, access) + def sig: String = { + s"$addAnnotations${pattern(name, access)}" + } + def file = filepattern(name) + private def addAnnotations: String = { + val annotations = sym.annotations + .filter(a => allowedAnnotations.contains(a.symbol.fullName('.'))) + .map { a => s"@${a.symbol.fullName('.')}" } + .mkString(System.lineSeparator()) + if (!annotations.isEmpty) { + annotations + System.lineSeparator() + } else { + annotations + } + } + def addMember(t: Templ) = copy(members = members :+ t) def constructor: Boolean = { @@ -49,7 +64,7 @@ trait AST { this: TransformCake => object ClassInfo { def apply(c: ImplDef, comment: Seq[String], topLevel: Boolean): ClassInfo = { c match { - case ClassDef(mods, _, tparams, impl) => + case cd@ClassDef(mods, _, tparams, impl) => val name = c.name.toString val acc = access(mods, topLevel) val fl = flags(mods) @@ -93,9 +108,27 @@ trait AST { this: TransformCake => } } - case class MethodInfo(access: String, pattern: String => String, ret: String, name: String, comment: Seq[String]) extends Templ { - def sig = pattern(s"$ret $name") + case class MethodInfo(access: String, pattern: String => String, ret: String, name: String, comment: Seq[String], d: Option[DefDef] = None) extends Templ { + def sig: String = { + s"$addAnnotations${pattern(s"$ret $name")}" + } + + private def addAnnotations: String = d match { + case Some(definition) => { + val annotations = definition.symbol.annotations + .filter(a => allowedAnnotations.contains(a.symbol.fullName('.'))) + .map { a => s"@${a.symbol.fullName('.')}" } + .mkString(System.lineSeparator()) + if (!annotations.isEmpty) { + annotations + System.lineSeparator() + } else { + annotations + } + } + case None => "" + } } + object MethodInfo { def apply(d: DefDef, interface: Boolean, comment: Seq[String], hasVararg: Boolean, deprecation: Option[DeprecationInfo]): MethodInfo = { val acc = methodAccess(d.symbol, interface) + methodFlags(d.mods, interface) @@ -139,7 +172,7 @@ trait AST { this: TransformCake => case Some(deprec) => deprec.appendToComment(commentWithParams) case _ => commentWithParams } - MethodInfo(acc, pattern, ret, name, commentWithParamsAndDeprec) + MethodInfo(acc, pattern, ret, name, commentWithParamsAndDeprec, Some(d)) } /** diff --git a/plugin/src/main/scala/com/typesafe/genjavadoc/Plugin.scala b/plugin/src/main/scala/com/typesafe/genjavadoc/Plugin.scala index 23fac0b..37c7af6 100644 --- a/plugin/src/main/scala/com/typesafe/genjavadoc/Plugin.scala +++ b/plugin/src/main/scala/com/typesafe/genjavadoc/Plugin.scala @@ -8,6 +8,7 @@ import nsc.transform.Transform import java.io.File import java.util.Properties + object GenJavadocPlugin { val javaKeywords = Set("abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const", "continue", @@ -48,6 +49,7 @@ class GenJavadocPlugin(val global: Global) extends Plugin { lazy val filteredStrings: Set[String] = stringToFilter(myOptions.getProperty("filter", defaultFilterString)) lazy val fabricateParams = java.lang.Boolean.parseBoolean(myOptions.getProperty("fabricateParams", "true")) lazy val strictVisibility = java.lang.Boolean.parseBoolean(myOptions.getProperty("strictVisibility", "false")) + lazy val allowedAnnotations: Set[String] = stringToFilter(myOptions.getProperty("annotations", "")) private object MyComponent extends PluginComponent with Transform { @@ -78,6 +80,8 @@ class GenJavadocPlugin(val global: Global) extends Plugin { override def transformUnit(unit: CompilationUnit) = newTransformUnit(unit) override def javaKeywords = GenJavadocPlugin.javaKeywords override def filteredStrings = GenJavadocPlugin.this.filteredStrings + + override def allowedAnnotations: Set[String] = GenJavadocPlugin.this.allowedAnnotations } } } diff --git a/plugin/src/main/scala/com/typesafe/genjavadoc/TransformCake.scala b/plugin/src/main/scala/com/typesafe/genjavadoc/TransformCake.scala index 633709a..b3c71bf 100644 --- a/plugin/src/main/scala/com/typesafe/genjavadoc/TransformCake.scala +++ b/plugin/src/main/scala/com/typesafe/genjavadoc/TransformCake.scala @@ -14,4 +14,6 @@ trait TransformCake extends JavaSig with Output with Comments with BasicTransfor def javaKeywords: Set[String] def filteredStrings: Set[String] + + def allowedAnnotations: Set[String] } diff --git a/plugin/src/test/resources/expected_output/basic/akka/WithAnnotation.java b/plugin/src/test/resources/expected_output/basic/akka/WithAnnotation.java new file mode 100644 index 0000000..65bfee6 --- /dev/null +++ b/plugin/src/test/resources/expected_output/basic/akka/WithAnnotation.java @@ -0,0 +1,5 @@ +package akka; +@java.lang.SuppressWarnings +public class WithAnnotation { + public WithAnnotation () { throw new RuntimeException(); } +} diff --git a/plugin/src/test/resources/input/basic/akka/WithAnnotation.scala b/plugin/src/test/resources/input/basic/akka/WithAnnotation.scala new file mode 100644 index 0000000..f783737 --- /dev/null +++ b/plugin/src/test/resources/input/basic/akka/WithAnnotation.scala @@ -0,0 +1,4 @@ +package akka + +@SuppressWarnings(value=Array("")) +class WithAnnotation \ No newline at end of file diff --git a/plugin/src/test/scala/com/typesafe/genjavadoc/BasicSpec.scala b/plugin/src/test/scala/com/typesafe/genjavadoc/BasicSpec.scala index dd1d889..782ed12 100644 --- a/plugin/src/test/scala/com/typesafe/genjavadoc/BasicSpec.scala +++ b/plugin/src/test/scala/com/typesafe/genjavadoc/BasicSpec.scala @@ -13,6 +13,7 @@ object BasicSpec { /** Test basic behaviour of genjavadoc with standard settings */ class BasicSpec extends CompilerSpec { + override def extraSettings: Seq[String] = Seq("annotations=java.lang.SuppressWarnings") override def sources = BasicSpec.sources override def expectedPath: String = { val scalaVersion = scala.util.Properties.versionNumberString.split("-").head