GH-97 Add basic support for passing annotations to the generated Java stubs (#171)

Author: ilx

README.md

@@ -103,6 +103,36 @@ GenJavadoc can also be integrated into a Maven build (inspired by [this answer o
 </profile>
 ~~~
 
+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:

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))
     }
 
     /**

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
     }
   }
 }

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]
 }

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(); }
+}

plugin/src/test/resources/input/basic/akka/WithAnnotation.scala

@@ -0,0 +1,4 @@
+package akka
+
+@SuppressWarnings(value=Array(""))
+class WithAnnotation

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