Support multiple tag names for a single inline tag in doc comments (#150

)

Resolves: #56
Signed-off-by: Daniel Kamkha <daniel.kamkha@here.com>

CHANGELOG.md

@@ -3,8 +3,9 @@
 ## Unreleased
 ### Features
   * Structs marked as `@Serializable` in IDL now conform to `Codable` protocol in Swift.
+  * Added support for specifying multiple platform names in a single inline tag in documentation
+    comments (e.g. `foo {@Cpp @Java bar}`).
 
-## 6.2.0
 Release date: 2020-02-20
 ### Features
   * Experimental support for generating Dart bindings.

docs/lime_idl.md

@@ -547,6 +547,11 @@ The resulting documentation will look like this, per language:
 Note that one space after the `@Platform` is treated as separator, everything after that, including
 spaces is considered to be part of the comment.
 
+Multiple platform tags can be combined in a single `{@ }` section, if necessary:
+```
+// Process something{@Cpp @Java  the right way}.
+```
+
 #### Special characters in documentation comments
 
 Special characters `@`, `{`, `}`, and `\` can be used in documentation comments only if they are

gluecodium/src/test/resources/smoke/comments/input/PlatformComments.lime

@@ -38,4 +38,9 @@ class PlatformComments {
     // @return {@Cpp Usefulness}{@Java Uselessness [SomeEnum]}{@Swift Usefulness} of the input
     // @throws Sometimes it happens{@Swift  but not on iOS [SomethingWrong] \\esc\@pe\{s\} }.
     fun someMethodWithAllComments(input: String): Boolean throws SomethingWrong
+
+    // This is a{@Cpp @Java  very}{@Java @Swift  super}{@Swift @Cpp  useful}{@Cpp @Java @Swift  struct}.
+    struct something {
+        nothing: String
+    }
 }

gluecodium/src/test/resources/smoke/comments/output/android/com/example/smoke/PlatformComments.java

@@ -23,6 +23,16 @@ public SomethingWrongException(final PlatformComments.SomeEnum error) {
         }
         public final PlatformComments.SomeEnum error;
     }
+    /**
+     * <p>This is a very super struct.</p>
+     */
+    public final static class Something {
+        @NonNull
+        public String nothing;
+        public Something(@NonNull final String nothing) {
+            this.nothing = nothing;
+        }
+    }
     /**
      * For internal use only.
      * @exclude

gluecodium/src/test/resources/smoke/comments/output/cpp/include/smoke/PlatformComments.h

@@ -21,6 +21,14 @@ class _GLUECODIUM_CPP_EXPORT PlatformComments {
         USELESS,
         USEFUL
     };
+    /**
+     * This is a very useful struct.
+     */
+    struct _GLUECODIUM_CPP_EXPORT Something {
+        ::std::string nothing;
+        Something( );
+        Something( const ::std::string& nothing );
+    };
 public:
     /**
      * This is some very useless method that does nothing.

gluecodium/src/test/resources/smoke/comments/output/lime/smoke/PlatformComments.lime

@@ -7,6 +7,10 @@ class PlatformComments {
     }
     // An {@Java exception}{@Swift error} when something goes wrong.
     exception SomethingWrong(SomeEnum)
+    // This is a{@Cpp  very}{@Java  very}{@Java  super}{@Swift  super}{@Swift  useful}{@Cpp  useful}{@Cpp  struct}{@Java  struct}{@Swift  struct}.
+    struct something {
+        nothing: String
+    }
     // This is some very useless method that {@Cpp does nothing}{@Java makes some coffee}{@Swift is very swift}.
     fun doNothing()
     // {@Cpp Cooks very special C++ sauce.}{@Java Makes some coffee.}{@Swift Eats a hip bruschetta.}

gluecodium/src/test/resources/smoke/comments/output/swift/smoke/PlatformComments.swift

@@ -18,6 +18,16 @@ public class PlatformComments {
         case useless
         case useful
     }
+    /// This is a super useful struct.
+    public struct Something {
+        public var nothing: String
+        public init(nothing: String) {
+            self.nothing = nothing
+        }
+        internal init(cHandle: _baseRef) {
+            nothing = moveFromCType(smoke_PlatformComments_Something_nothing_get(cHandle))
+        }
+    }
     /// This is some very useless method that is very swift.
     public func doNothing() -> Void {
         return moveFromCType(smoke_PlatformComments_doNothing(self.c_instance))
@@ -82,6 +92,45 @@ internal func copyToCType(_ swiftClass: PlatformComments?) -> RefHolder {
 internal func moveToCType(_ swiftClass: PlatformComments?) -> RefHolder {
     return getRef(swiftClass, owning: true)
 }
+internal func copyFromCType(_ handle: _baseRef) -> PlatformComments.Something {
+    return PlatformComments.Something(cHandle: handle)
+}
+internal func moveFromCType(_ handle: _baseRef) -> PlatformComments.Something {
+    defer {
+        smoke_PlatformComments_Something_release_handle(handle)
+    }
+    return copyFromCType(handle)
+}
+internal func copyToCType(_ swiftType: PlatformComments.Something) -> RefHolder {
+    let c_nothing = moveToCType(swiftType.nothing)
+    return RefHolder(smoke_PlatformComments_Something_create_handle(c_nothing.ref))
+}
+internal func moveToCType(_ swiftType: PlatformComments.Something) -> RefHolder {
+    return RefHolder(ref: copyToCType(swiftType).ref, release: smoke_PlatformComments_Something_release_handle)
+}
+internal func copyFromCType(_ handle: _baseRef) -> PlatformComments.Something? {
+    guard handle != 0 else {
+        return nil
+    }
+    let unwrappedHandle = smoke_PlatformComments_Something_unwrap_optional_handle(handle)
+    return PlatformComments.Something(cHandle: unwrappedHandle) as PlatformComments.Something
+}
+internal func moveFromCType(_ handle: _baseRef) -> PlatformComments.Something? {
+    defer {
+        smoke_PlatformComments_Something_release_optional_handle(handle)
+    }
+    return copyFromCType(handle)
+}
+internal func copyToCType(_ swiftType: PlatformComments.Something?) -> RefHolder {
+    guard let swiftType = swiftType else {
+        return RefHolder(0)
+    }
+    let c_nothing = moveToCType(swiftType.nothing)
+    return RefHolder(smoke_PlatformComments_Something_create_optional_handle(c_nothing.ref))
+}
+internal func moveToCType(_ swiftType: PlatformComments.Something?) -> RefHolder {
+    return RefHolder(ref: copyToCType(swiftType).ref, release: smoke_PlatformComments_Something_release_optional_handle)
+}
 internal func copyToCType(_ swiftEnum: PlatformComments.SomeEnum) -> PrimitiveHolder<UInt32> {
     return PrimitiveHolder(swiftEnum.rawValue)
 }

gradle/spotless.gradle

@@ -22,7 +22,7 @@ spotless {
     java {
         target project.fileTree(project.projectDir) {
             include '**/*.java'
-            exclude '**/build', '**/test/resources'
+            exclude '**/build', '**/test/resources', '**/gen'
         }
         googleJavaFormat()
         licenseHeaderFile rootProject.file('config/spotless/here_java.license')

lime-loader/src/main/antlr/LimedocParser.g4

@@ -76,7 +76,7 @@ blockTagContent
     ;
 
 inlineTag
-      : '{@' tagName WhiteSpace inlineTagContent* '}'
+      : '{@' tagName (WhiteSpace '@' tagName)* WhiteSpace inlineTagContent* '}'
       ;
 
 inlineTagContent

lime-loader/src/main/java/com/here/gluecodium/loader/AntlrLimedocBuilder.kt

@@ -48,14 +48,14 @@ internal class AntlrLimedocBuilder : LimedocParserBaseListener() {
     override fun exitDecriptionFirstWord(ctx: LimedocParser.DecriptionFirstWordContext) {
         contentCollector += when {
             ctx.inlineTag() != null -> convertInlineTag(ctx.inlineTag())
-            else -> "" to ctx.text
+            else -> listOf("" to ctx.text)
         }
     }
 
     override fun exitDescriptionContent(ctx: LimedocParser.DescriptionContentContext) {
         contentCollector += when {
             ctx.inlineTag() != null -> convertInlineTag(ctx.inlineTag())
-            else -> "" to unescapeText(ctx.text)
+            else -> listOf("" to unescapeText(ctx.text))
         }
     }
 
@@ -69,14 +69,16 @@ internal class AntlrLimedocBuilder : LimedocParserBaseListener() {
     override fun exitBlockTagContent(ctx: LimedocParser.BlockTagContentContext) {
         contentCollector += when {
             ctx.inlineTag() != null -> convertInlineTag(ctx.inlineTag())
-            else -> "" to unescapeText(ctx.text)
+            else -> listOf("" to unescapeText(ctx.text))
         }
     }
 
     // Private functions
 
-    private fun convertInlineTag(inlineTag: LimedocParser.InlineTagContext) =
-        inlineTag.tagName().text to inlineTag.inlineTagContent().joinToString("") { unescapeText(it.text) }
+    private fun convertInlineTag(inlineTag: LimedocParser.InlineTagContext): List<Pair<String, String>> {
+        val tagContent = inlineTag.inlineTagContent().joinToString("") { unescapeText(it.text) }
+        return inlineTag.tagName().map { it.text to tagContent }
+    }
 
     private fun unescapeText(text: String) =
         text.replace("""\\(@|\{|\}|\\)""".toRegex()) { it.groupValues[1] }