Repository: square/kotlinpoet (kotlin)

Issue:
Support multiline comments in FileSpec
Add `FileSpec.addKDoc()`

Pull request description:
This changes behavior to emit in format:
```kotlin
/**
 * MULTI LINE
 * COMMENT
 */
```

instead of
```kotlin
// MULTI LINE
// COMMENT
```
when the comments are more than one line. 

Resolves #358

Patch:
diff --git a/src/main/java/com/squareup/kotlinpoet/FileSpec.kt b/src/main/java/com/squareup/kotlinpoet/FileSpec.kt
index 80390a4a9f..dc6c81e3a9 100644
--- a/src/main/java/com/squareup/kotlinpoet/FileSpec.kt
+++ b/src/main/java/com/squareup/kotlinpoet/FileSpec.kt
@@ -87,7 +87,11 @@ class FileSpec private constructor(builder: FileSpec.Builder) {
 
   private fun emit(codeWriter: CodeWriter) {
     if (comment.isNotEmpty()) {
-      codeWriter.emitComment(comment)
+      if (comment.isMultiLine()) {
+        codeWriter.emitKdoc(comment)
+      } else {
+        codeWriter.emitComment(comment)
+      }
     }
 
     if (annotations.isNotEmpty()) {
@@ -131,6 +135,10 @@ class FileSpec private constructor(builder: FileSpec.Builder) {
     codeWriter.popPackage()
   }
 
+  private fun CodeBlock.isMultiLine(): Boolean {
+    return this.toString().contains("\n")
+  }
+
   override fun equals(other: Any?): Boolean {
     if (this === other) return true
     if (other == null) return false
@@ -211,6 +219,10 @@ class FileSpec private constructor(builder: FileSpec.Builder) {
       comment.add(format, *args)
     }
 
+    fun addComment(comment: CodeBlock) = apply {
+      this.comment.add(comment)
+    }
+
     fun addType(typeSpec: TypeSpec) = apply {
       members += typeSpec
     }


Test patch:
diff --git a/src/test/java/com/squareup/kotlinpoet/FileSpecTest.kt b/src/test/java/com/squareup/kotlinpoet/FileSpecTest.kt
index 75000d3157..a0b90d36fd 100644
--- a/src/test/java/com/squareup/kotlinpoet/FileSpecTest.kt
+++ b/src/test/java/com/squareup/kotlinpoet/FileSpecTest.kt
@@ -571,17 +571,60 @@ class FileSpecTest {
         .addComment("\nGENERATED FILE:\n\nDO NOT EDIT!\n")
         .build()
     assertThat(source.toString()).isEqualTo("""
-        |//
-        |// GENERATED FILE:
-        |//
-        |// DO NOT EDIT!
-        |//
+        |/**
+        | *
+        | * GENERATED FILE:
+        | *
+        | * DO NOT EDIT!
+        | */
         |package com.squareup.tacos
         |
         |class Taco
         |""".trimMargin())
   }
 
+  @Test fun multiLineFileHeaderComment() {
+    val source = FileSpec.builder("com.squareup.tacos", "Taco")
+        .addType(TypeSpec.classBuilder("Taco").build())
+        .addComment(CodeBlock.builder()
+            .addStatement("Copyright (C) 2015 Square, Inc.")
+            .add("\n")
+            .addStatement("Licensed under the Apache License, Version 2.0 (the \"License\");")
+            .addStatement("you may not use this file except in compliance with the License.")
+            .addStatement("You may obtain a copy of the License at")
+            .add("\n")
+            .addStatement("http://www.apache.org/licenses/LICENSE-2.0")
+            .add("\n")
+            .addStatement("Unless required by applicable law or agreed to in writing, software")
+            .addStatement("distributed under the License is distributed on an \"AS IS\" BASIS,")
+            .addStatement("WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.")
+            .addStatement("See the License for the specific language governing permissions and")
+            .addStatement("limitations under the License.")
+            .build())
+        .build()
+
+    assertThat(source.toString()).isEqualTo("""
+      |/**
+      | * Copyright (C) 2015 Square, Inc.
+      | *
+      | * Licensed under the Apache License, Version 2.0 (the "License");
+      | * you may not use this file except in compliance with the License.
+      | * You may obtain a copy of the License at
+      | *
+      | * http://www.apache.org/licenses/LICENSE-2.0
+      | *
+      | * Unless required by applicable law or agreed to in writing, software
+      | * distributed under the License is distributed on an "AS IS" BASIS,
+      | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      | * See the License for the specific language governing permissions and
+      | * limitations under the License.
+      | */
+      |package com.squareup.tacos
+      |
+      |class Taco
+      |""".trimMargin())
+  }
+
   @Test fun packageClassConflictsWithNestedClass() {
     val source = FileSpec.builder("com.squareup.tacos", "Taco")
         .addType(TypeSpec.classBuilder("Taco")