[pigeon] Adds Kotlin documentation comment support (#2665)

Author: tarrinneal

packages/pigeon/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.2.1
+
+* Adds documentation comment support for Kotlin.
+
 ## 4.2.0
 
 * Adds experimental support for Kotlin generation.

packages/pigeon/lib/generator_tools.dart

@@ -9,7 +9,7 @@ import 'dart:mirrors';
 import 'ast.dart';
 
 /// The current version of pigeon. This must match the version in pubspec.yaml.
-const String pigeonVersion = '4.2.0';
+const String pigeonVersion = '4.2.1';
 
 /// Read all the content from [stdin] to a String.
 String readStdin() {

packages/pigeon/lib/kotlin_generator.dart

@@ -7,6 +7,23 @@ import 'functional.dart';
 import 'generator_tools.dart';
 import 'pigeon_lib.dart' show TaskQueueType;
 
+/// Documentation open symbol.
+const String _docCommentPrefix = '/**';
+
+/// Documentation continuation symbol.
+const String _docCommentContinuation = ' *';
+
+/// Documentation close symbol.
+const String _docCommentSuffix = ' */';
+
+/// Documentation comment spec.
+const DocumentCommentSpecification _docCommentSpec =
+    DocumentCommentSpecification(
+  _docCommentPrefix,
+  closeCommentToken: _docCommentSuffix,
+  blockContinuationToken: _docCommentContinuation,
+);
+
 /// Options that control how Kotlin code will be generated.
 class KotlinOptions {
   /// Creates a [KotlinOptions] object
@@ -112,8 +129,12 @@ void _writeHostApi(Indent indent, Api api, Root root) {
 
   final String apiName = api.name;
 
-  indent.writeln(
-      '/** Generated interface from Pigeon that represents a handler of messages from Flutter. */');
+  const List<String> generatedMessages = <String>[
+    ' Generated interface from Pigeon that represents a handler of messages from Flutter.'
+  ];
+  addDocumentationComments(indent, api.documentationComments, _docCommentSpec,
+      generatorComments: generatedMessages);
+
   indent.write('interface $apiName ');
   indent.scoped('{', '}', () {
     for (final Method method in api.methods) {
@@ -132,6 +153,10 @@ void _writeHostApi(Indent indent, Api api, Root root) {
       final String returnType = method.returnType.isVoid
           ? ''
           : _nullsafeKotlinTypeForDartType(method.returnType);
+
+      addDocumentationComments(
+          indent, method.documentationComments, _docCommentSpec);
+
       if (method.isAsynchronous) {
         argSignature.add('callback: ($returnType) -> Unit');
         indent.writeln('fun ${method.name}(${argSignature.join(', ')})');
@@ -256,8 +281,12 @@ String _getSafeArgumentName(int count, NamedType argument) =>
 /// }
 void _writeFlutterApi(Indent indent, Api api) {
   assert(api.location == ApiLocation.flutter);
-  indent.writeln(
-      '/** Generated class from Pigeon that represents Flutter messages that can be called from Kotlin. */');
+  const List<String> generatedMessages = <String>[
+    ' Generated class from Pigeon that represents Flutter messages that can be called from Kotlin.'
+  ];
+  addDocumentationComments(indent, api.documentationComments, _docCommentSpec,
+      generatorComments: generatedMessages);
+
   final String apiName = api.name;
   indent.writeln('@Suppress("UNCHECKED_CAST")');
   indent.write('class $apiName(private val binaryMessenger: BinaryMessenger) ');
@@ -277,6 +306,10 @@ void _writeFlutterApi(Indent indent, Api api) {
           ? ''
           : _nullsafeKotlinTypeForDartType(func.returnType);
       String sendArgument;
+
+      addDocumentationComments(
+          indent, func.documentationComments, _docCommentSpec);
+
       if (func.arguments.isEmpty) {
         indent.write('fun ${func.name}(callback: ($returnType) -> Unit) ');
         sendArgument = 'null';
@@ -430,6 +463,8 @@ void generateKotlin(KotlinOptions options, Root root, StringSink sink) {
   }
 
   void writeEnum(Enum anEnum) {
+    addDocumentationComments(
+        indent, anEnum.documentationComments, _docCommentSpec);
     indent.write('enum class ${anEnum.name}(val raw: Int) ');
     indent.scoped('{', '}', () {
       // We use explicit indexing here as use of the ordinal() method is
@@ -460,6 +495,8 @@ void generateKotlin(KotlinOptions options, Root root, StringSink sink) {
 
   void writeDataClass(Class klass) {
     void writeField(NamedType field) {
+      addDocumentationComments(
+          indent, field.documentationComments, _docCommentSpec);
       indent.write(
           'val ${field.name}: ${_nullsafeKotlinTypeForDartType(field.type)}');
       final String defaultNil = field.type.isNullable ? ' = null' : '';
@@ -566,8 +603,13 @@ void generateKotlin(KotlinOptions options, Root root, StringSink sink) {
       });
     }
 
-    indent.writeln(
-        '/** Generated class from Pigeon that represents data sent in messages. */');
+    const List<String> generatedMessages = <String>[
+      ' Generated class from Pigeon that represents data sent in messages.'
+    ];
+    addDocumentationComments(
+        indent, klass.documentationComments, _docCommentSpec,
+        generatorComments: generatedMessages);
+
     indent.write('data class ${klass.name}(');
     indent.scoped('', '', () {
       for (final NamedType element in klass.fields) {

packages/pigeon/pubspec.yaml

@@ -2,7 +2,7 @@ name: pigeon
 description: Code generator tool to make communication between Flutter and the host platform type-safe and easier.
 repository: https://github.com/flutter/packages/tree/main/packages/pigeon
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3Apigeon
-version: 4.2.0 # This must match the version in lib/generator_tools.dart
+version: 4.2.1 # This must match the version in lib/generator_tools.dart
 
 environment:
   sdk: ">=2.12.0 <3.0.0"

packages/pigeon/test/kotlin_generator_test.dart

@@ -993,4 +993,81 @@ void main() {
     final String code = sink.toString();
     expect(code, contains('val input: String\n'));
   });
+
+  test('transfers documentation comments', () {
+    final List<String> comments = <String>[
+      ' api comment',
+      ' api method comment',
+      ' class comment',
+      ' class field comment',
+      ' enum comment',
+    ];
+    int count = 0;
+
+    final Root root = Root(
+      apis: <Api>[
+        Api(
+          name: 'api',
+          location: ApiLocation.flutter,
+          documentationComments: <String>[comments[count++]],
+          methods: <Method>[
+            Method(
+              name: 'method',
+              returnType: const TypeDeclaration.voidDeclaration(),
+              documentationComments: <String>[comments[count++]],
+              arguments: <NamedType>[
+                NamedType(
+                  name: 'field',
+                  type: const TypeDeclaration(
+                    baseName: 'int',
+                    isNullable: true,
+                  ),
+                ),
+              ],
+            )
+          ],
+        )
+      ],
+      classes: <Class>[
+        Class(
+          name: 'class',
+          documentationComments: <String>[comments[count++]],
+          fields: <NamedType>[
+            NamedType(
+              documentationComments: <String>[comments[count++]],
+              type: const TypeDeclaration(
+                  baseName: 'Map',
+                  isNullable: true,
+                  typeArguments: <TypeDeclaration>[
+                    TypeDeclaration(baseName: 'String', isNullable: true),
+                    TypeDeclaration(baseName: 'int', isNullable: true),
+                  ]),
+              name: 'field1',
+            ),
+          ],
+        ),
+      ],
+      enums: <Enum>[
+        Enum(
+          name: 'enum',
+          documentationComments: <String>[comments[count++]],
+          members: <String>[
+            'one',
+            'two',
+          ],
+        ),
+      ],
+    );
+    final StringBuffer sink = StringBuffer();
+    const KotlinOptions kotlinOptions = KotlinOptions();
+    generateKotlin(kotlinOptions, root, sink);
+    final String code = sink.toString();
+    for (final String comment in comments) {
+      // This regex finds the comment only between the open and close comment block
+      expect(
+          RegExp(r'(?<=\/\*\*.*?)' + comment + r'(?=.*?\*\/)', dotAll: true)
+              .hasMatch(code),
+          true);
+    }
+  });
 }