From 9d1189486224e88134cad4e934390b0661e3f68d Mon Sep 17 00:00:00 2001
From: John Firebaugh <john.firebaugh@gmail.com>
Date: Tue, 17 Jul 2018 16:15:37 -0700
Subject: [PATCH 1/5] Fix run and run-assume-built scripts when CDPATH is set
 (#358)

When the CDPATH environment variable is set, the cd command prints the path of the directory to stdout. Redirect that output to /dev/null to avoid it being mistakenly included in the base_dir variable, which then causes cryptic errors.
---
 src/run              | 2 +-
 src/run-assume-built | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/run b/src/run
index df98763bc..caea5c3b0 100755
--- a/src/run
+++ b/src/run
@@ -12,7 +12,7 @@ while [ -h "$loc" ]; do
         loc="`dirname "$loc"`/$link"  # Relative link
     fi
 done
-base_dir=$(cd "`dirname "$loc"`" && pwd)
+base_dir=$(cd "`dirname "$loc"`" > /dev/null && pwd)
 
 "$base_dir/build"
 
diff --git a/src/run-assume-built b/src/run-assume-built
index 9502973b4..6d2a50bcb 100755
--- a/src/run-assume-built
+++ b/src/run-assume-built
@@ -12,6 +12,6 @@ while [ -h "$loc" ]; do
         loc="`dirname "$loc"`/$link"  # Relative link
     fi
 done
-base_dir=$(cd "`dirname "$loc"`" && pwd)
+base_dir=$(cd "`dirname "$loc"`" > /dev/null && pwd)
 
 exec "$base_dir/target/start" "$@"

From 6986cc43d95387f58e56365c2d299a20e74f2606 Mon Sep 17 00:00:00 2001
From: Xianwen Chen <xianwen@dropbox.com>
Date: Wed, 18 Jul 2018 10:38:54 -0700
Subject: [PATCH 2/5] =?UTF-8?q?Fix=20error=20=E2=80=98constexpr=E2=80=99?=
 =?UTF-8?q?=20needed=20for=20in-class=20initialization=20of=20static=20dat?=
 =?UTF-8?q?a=20member=20(#387)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/source/CppGenerator.scala                    |  2 +-
 test-suite/generated-src/cpp/constants.cpp       | 16 ++++++++--------
 .../generated-src/cpp/constants_interface.cpp    | 14 +++++++-------
 3 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/src/source/CppGenerator.scala b/src/source/CppGenerator.scala
index 4902c4adc..d253dda3a 100644
--- a/src/source/CppGenerator.scala
+++ b/src/source/CppGenerator.scala
@@ -175,7 +175,7 @@ class CppGenerator(spec: Spec) extends Generator(spec) {
     for (c <- consts) {
       skipFirst{ w.wl }
       if (shouldConstexpr(c)){
-        w.w(s"${marshal.fieldType(c.ty)} const $selfName::${idCpp.const(c.ident)}")
+        w.w(s"${marshal.fieldType(c.ty)} constexpr $selfName::${idCpp.const(c.ident)}")
       } else {
         w.w(s"${marshal.fieldType(c.ty)} const $selfName::${idCpp.const(c.ident)} = ")
         writeCppConst(w, c.ty, c.value)
diff --git a/test-suite/generated-src/cpp/constants.cpp b/test-suite/generated-src/cpp/constants.cpp
index c9fcafb41..d21ba16c2 100644
--- a/test-suite/generated-src/cpp/constants.cpp
+++ b/test-suite/generated-src/cpp/constants.cpp
@@ -5,19 +5,19 @@
 
 namespace testsuite {
 
-bool const Constants::BOOL_CONSTANT;
+bool constexpr Constants::BOOL_CONSTANT;
 
-int8_t const Constants::I8_CONSTANT;
+int8_t constexpr Constants::I8_CONSTANT;
 
-int16_t const Constants::I16_CONSTANT;
+int16_t constexpr Constants::I16_CONSTANT;
 
-int32_t const Constants::I32_CONSTANT;
+int32_t constexpr Constants::I32_CONSTANT;
 
-int64_t const Constants::I64_CONSTANT;
+int64_t constexpr Constants::I64_CONSTANT;
 
-float const Constants::F32_CONSTANT;
+float constexpr Constants::F32_CONSTANT;
 
-double const Constants::F64_CONSTANT;
+double constexpr Constants::F64_CONSTANT;
 
 std::experimental::optional<bool> const Constants::OPT_BOOL_CONSTANT = true;
 
@@ -41,6 +41,6 @@ ConstantRecord const Constants::OBJECT_CONSTANT = ConstantRecord(
     Constants::I32_CONSTANT /* some_integer */ ,
     Constants::STRING_CONSTANT /* some_string */ );
 
-bool const Constants::DUMMY;
+bool constexpr Constants::DUMMY;
 
 }  // namespace testsuite
diff --git a/test-suite/generated-src/cpp/constants_interface.cpp b/test-suite/generated-src/cpp/constants_interface.cpp
index 27f93ae56..3633110f7 100644
--- a/test-suite/generated-src/cpp/constants_interface.cpp
+++ b/test-suite/generated-src/cpp/constants_interface.cpp
@@ -6,19 +6,19 @@
 
 namespace testsuite {
 
-bool const ConstantsInterface::BOOL_CONSTANT;
+bool constexpr ConstantsInterface::BOOL_CONSTANT;
 
-int8_t const ConstantsInterface::I8_CONSTANT;
+int8_t constexpr ConstantsInterface::I8_CONSTANT;
 
-int16_t const ConstantsInterface::I16_CONSTANT;
+int16_t constexpr ConstantsInterface::I16_CONSTANT;
 
-int32_t const ConstantsInterface::I32_CONSTANT;
+int32_t constexpr ConstantsInterface::I32_CONSTANT;
 
-int64_t const ConstantsInterface::I64_CONSTANT;
+int64_t constexpr ConstantsInterface::I64_CONSTANT;
 
-float const ConstantsInterface::F32_CONSTANT;
+float constexpr ConstantsInterface::F32_CONSTANT;
 
-double const ConstantsInterface::F64_CONSTANT;
+double constexpr ConstantsInterface::F64_CONSTANT;
 
 std::experimental::optional<bool> const ConstantsInterface::OPT_BOOL_CONSTANT = true;
 

From a8325df7862d389b894cbe47e7fad14b0fd38f70 Mon Sep 17 00:00:00 2001
From: Bruno Coelho <4brunu@users.noreply.github.com>
Date: Wed, 18 Jul 2018 18:51:25 +0100
Subject: [PATCH 3/5] Add Android Parcelable records documentation (#382)

---
 README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/README.md b/README.md
index 79aca3edb..31e32f978 100644
--- a/README.md
+++ b/README.md
@@ -507,6 +507,14 @@ For more informations, take a look at https://github.com/leetal/ios-cmake.
 
 - `ENABLE_BITCODE`: enable/disable the bitcode generation.
 
+## Android Parcelable records
+
+Djinni supports generating records that implements `android.os.parcelable`.
+
+In order to do that, there are two steps needed:
+- deriving the records that should be parcelable with the keyword parcelable: `deriving(parcelable)`
+- run Djinni with the following flag `--java-implement-android-os-parcelable true`
+
 ## Community Links
 
 * Join the discussion with other developers at the [Mobile C++ Slack Community](https://mobilecpp.herokuapp.com/)

From 0ee3da6c5560981b4b19f7e018c3873bce68ecc5 Mon Sep 17 00:00:00 2001
From: Bruno Coelho <4brunu@users.noreply.github.com>
Date: Wed, 18 Jul 2018 19:34:37 +0100
Subject: [PATCH 4/5] Implement comments support (#379)

* Implement comments support, tests and readme documentation

* improve code comments and documents comments parser when the two types of comments are one after the other

* improve tests
---
 README.md                                     |  4 ++
 example/example.djinni                        |  2 +-
 example/generated-src/cpp/sort_items.hpp      |  2 +-
 .../java/com/dropbox/textsort/SortItems.java  |  2 +-
 example/generated-src/objc/TXSSortItems.h     |  2 +-
 src/source/ast.scala                          |  8 ++-
 src/source/generator.scala                    | 51 ++++++++++++-----
 src/source/parser.scala                       | 57 ++++++++++++++++++-
 test-suite/djinni/client_interface.djinni     | 20 ++++++-
 test-suite/djinni/constant_enum.djinni        |  2 +-
 test-suite/djinni/constants.djinni            | 10 +++-
 test-suite/djinni/enum.djinni                 |  3 +
 test-suite/djinni/multiple_inheritance.djinni |  4 +-
 test-suite/djinni/yaml-test.djinni            |  2 +
 .../generated-src/cpp/client_interface.hpp    |  5 +-
 .../cpp/client_returned_record.hpp            |  2 +-
 test-suite/generated-src/cpp/color.hpp        |  3 +
 test-suite/generated-src/cpp/constants.hpp    | 12 ++--
 .../generated-src/cpp/constants_interface.hpp |  8 +--
 .../generated-src/cpp/extern_interface_1.hpp  |  1 +
 test-suite/generated-src/cpp/return_two.hpp   |  2 +-
 .../cpp/reverse_client_interface.hpp          | 16 ++++++
 .../generated-src/cpp/second_listener.hpp     |  2 +-
 .../dropbox/djinni/test/ClientInterface.java  |  5 +-
 .../djinni/test/ClientReturnedRecord.java     |  2 +-
 .../java/com/dropbox/djinni/test/Color.java   |  3 +
 .../com/dropbox/djinni/test/ConstantEnum.java |  2 +-
 .../com/dropbox/djinni/test/Constants.java    | 12 ++--
 .../djinni/test/ConstantsInterface.java       |  8 +--
 .../dropbox/djinni/test/ExternInterface1.java |  1 +
 .../com/dropbox/djinni/test/ReturnTwo.java    |  2 +-
 .../djinni/test/ReverseClientInterface.java   | 16 ++++++
 .../dropbox/djinni/test/SecondListener.java   |  2 +-
 .../generated-src/objc/DBClientInterface.h    |  5 +-
 .../objc/DBClientReturnedRecord.h             |  2 +-
 test-suite/generated-src/objc/DBColor.h       |  3 +
 .../generated-src/objc/DBConstantEnum.h       |  2 +-
 test-suite/generated-src/objc/DBConstants.h   | 12 ++--
 .../generated-src/objc/DBConstantsInterface.h |  8 +--
 .../generated-src/objc/DBExternInterface1.h   |  1 +
 test-suite/generated-src/objc/DBReturnTwo.h   |  2 +-
 .../objc/DBReverseClientInterface.h           | 16 ++++++
 .../generated-src/objc/DBSecondListener.h     |  2 +-
 43 files changed, 254 insertions(+), 72 deletions(-)

diff --git a/README.md b/README.md
index 31e32f978..f99a90b1e 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,10 @@ Djinni's input is an interface description file. Here's an example:
         store: set<string>;
         hash: map<string, i32>;
 
+        // You can generate two types of comments
+        // - Code comments by using "// comment" in djinni files which will generate "// comment" 
+        // - Code documentation by using "# comment" in djinni files which will generate "/** comment */" 
+        // Both of those types support single and multi line comments 
         values: list<another_record>;
 
         # Comments can also be put here
diff --git a/example/example.djinni b/example/example.djinni
index 55ee6de28..7ac70bbb5 100644
--- a/example/example.djinni
+++ b/example/example.djinni
@@ -9,7 +9,7 @@ sort_order = enum {
 }
 
 sort_items = interface +c {
-    # For the iOS / Android demo
+    // For the iOS / Android demo
     sort(order: sort_order, items: item_list);
     static create_with_listener(listener: textbox_listener): sort_items;
 
diff --git a/example/generated-src/cpp/sort_items.hpp b/example/generated-src/cpp/sort_items.hpp
index a01d3936c..1d0fc4174 100644
--- a/example/generated-src/cpp/sort_items.hpp
+++ b/example/generated-src/cpp/sort_items.hpp
@@ -15,7 +15,7 @@ class SortItems {
 public:
     virtual ~SortItems() {}
 
-    /** For the iOS / Android demo */
+    // For the iOS / Android demo
     virtual void sort(sort_order order, const ItemList & items) = 0;
 
     static std::shared_ptr<SortItems> create_with_listener(const std::shared_ptr<TextboxListener> & listener);
diff --git a/example/generated-src/java/com/dropbox/textsort/SortItems.java b/example/generated-src/java/com/dropbox/textsort/SortItems.java
index 03dbb82b4..51d860f12 100644
--- a/example/generated-src/java/com/dropbox/textsort/SortItems.java
+++ b/example/generated-src/java/com/dropbox/textsort/SortItems.java
@@ -8,7 +8,7 @@
 import javax.annotation.Nonnull;
 
 /*package*/ interface SortItems {
-    /** For the iOS / Android demo */
+    // For the iOS / Android demo
     public void sort(@Nonnull SortOrder order, @Nonnull ItemList items);
 
     @CheckForNull
diff --git a/example/generated-src/objc/TXSSortItems.h b/example/generated-src/objc/TXSSortItems.h
index f1da466bc..dfb134ffe 100644
--- a/example/generated-src/objc/TXSSortItems.h
+++ b/example/generated-src/objc/TXSSortItems.h
@@ -10,7 +10,7 @@
 
 @interface TXSSortItems : NSObject
 
-/** For the iOS / Android demo */
+// For the iOS / Android demo
 - (void)sort:(TXSSortOrder)order
        items:(nonnull TXSItemList *)items;
 
diff --git a/src/source/ast.scala b/src/source/ast.scala
index fb171240b..448694cdb 100644
--- a/src/source/ast.scala
+++ b/src/source/ast.scala
@@ -35,7 +35,13 @@ class EnumValue(val ty: Ident, ident: Ident) extends Ident(ident.name, ident.fil
 
 case class TypeParam(ident: Ident)
 
-case class Doc(lines: Seq[String])
+case class Doc(comments: Seq[Comment])
+
+abstract sealed class Comment {
+  val lines: Seq[String]
+}
+case class CodeComment(override val lines: Seq[String]) extends Comment
+case class DocComment(override val lines: Seq[String]) extends Comment
 
 sealed abstract class TypeDecl {
   val ident: Ident
diff --git a/src/source/generator.scala b/src/source/generator.scala
index 0151d89a7..b14479dc0 100644
--- a/src/source/generator.scala
+++ b/src/source/generator.scala
@@ -18,12 +18,15 @@ package djinni
 
 import djinni.ast._
 import java.io._
+
 import djinni.generatorTools._
 import djinni.meta._
 import djinni.syntax.Error
 import djinni.writer.IndentWriter
+
 import scala.language.implicitConversions
 import scala.collection.mutable
+import scala.collection.mutable.ArrayBuffer
 import scala.util.matching.Regex
 
 package object generatorTools {
@@ -425,22 +428,44 @@ abstract class Generator(spec: Spec)
 
   def writeMethodDoc(w: IndentWriter, method: Interface.Method, ident: IdentConverter) {
     val paramReplacements = method.params.map(p => (s"\\b${Regex.quote(p.ident.name)}\\b", s"${ident(p.ident.name)}"))
-    val newDoc = Doc(method.doc.lines.map(l => {
-      paramReplacements.foldLeft(l)((line, rep) =>
-        line.replaceAll(rep._1, rep._2))
-    }))
+
+    val comments = ArrayBuffer[Comment]()
+
+    method.doc.comments.foreach({
+      case DocComment(lines) =>
+
+        val newDocComment = DocComment(lines.map(l => {
+          paramReplacements.foldLeft(l)((line, rep) =>
+            line.replaceAll(rep._1, rep._2))
+        }))
+
+        comments += newDocComment
+
+      case CodeComment(lines) =>
+        comments += CodeComment(lines)
+    })
+
+    val newDoc = Doc(comments)
+
     writeDoc(w, newDoc)
   }
 
   def writeDoc(w: IndentWriter, doc: Doc) {
-    doc.lines.length match {
-      case 0 =>
-      case 1 =>
-        w.wl(s"/**${doc.lines.head} */")
-      case _ =>
-        w.wl("/**")
-        doc.lines.foreach (l => w.wl(s" *$l"))
-        w.wl(" */")
-    }
+    doc.comments.foreach({
+      case DocComment(lines) =>
+        lines.length match {
+          case 0 =>
+          case 1 =>
+            w.wl(s"/**${lines.head} */")
+          case _ =>
+            w.wl("/**")
+            lines.foreach (l => w.wl(s" *$l"))
+            w.wl(" */")
+        }
+
+      case CodeComment(lines) =>
+        lines.foreach (l => w.wl(s"//$l"))
+    })
   }
+
 }
diff --git a/src/source/parser.scala b/src/source/parser.scala
index 9e79e9960..392ac8a26 100644
--- a/src/source/parser.scala
+++ b/src/source/parser.scala
@@ -16,16 +16,19 @@
 
 package djinni
 
-import java.io.{File, FileNotFoundException, InputStreamReader, FileInputStream, Writer}
+import java.io.{File, FileInputStream, FileNotFoundException, InputStreamReader, Writer}
 
 import djinni.ast.Interface.Method
 import djinni.ast.Record.DerivingType.DerivingType
 import djinni.syntax._
 import djinni.ast._
 import java.util.{Map => JMap}
+
 import org.yaml.snakeyaml.Yaml
+
 import scala.collection.JavaConversions._
 import scala.collection.mutable
+import scala.collection.mutable.ArrayBuffer
 import scala.util.control.Breaks._
 import scala.util.parsing.combinator.RegexParsers
 import scala.util.parsing.input.{Position, Positional}
@@ -205,7 +208,57 @@ private object IdlParser extends RegexParsers {
     case (s, p) => Ident(s, fileStack.top, p)
   }
 
-  def doc: Parser[Doc] = rep(regex("""#[^\n\r]*""".r) ^^ (_.substring(1))) ^^ Doc
+  def doc: Parser[Doc] = rep(regex("""#[^\n\r]*""".r) | regex("""\/\/[^\n\r]*""".r)) ^^ { commentLines =>
+
+    val docCommentPrefix = "#"
+    val codeCommentPrefix = "//"
+
+    val comments = ArrayBuffer[Comment]()
+
+    commentLines.foreach( commentLine => {
+
+      if (commentLine.startsWith(docCommentPrefix)) { // DocComment
+
+        val commentText = commentLine.substring(docCommentPrefix.length)
+
+        if (comments.isEmpty) {
+          comments += DocComment(Seq(commentText))
+        } else {
+          comments.last match {
+            case DocComment(lines) =>
+              val newLines = lines :+ commentText
+              comments.remove(comments.length-1)
+              comments += DocComment(newLines)
+            case CodeComment(_) =>
+              comments += DocComment(Seq(commentText))
+          }
+        }
+
+      } else if (commentLine.startsWith(codeCommentPrefix)) { // CodeComment
+
+        val commentText = commentLine.substring(codeCommentPrefix.length)
+
+        if (comments.isEmpty) {
+          comments += CodeComment(Seq(commentText))
+        } else {
+          val commentText = commentLine.substring(codeCommentPrefix.length)
+          comments.last match {
+            case DocComment(_) =>
+              comments += CodeComment(Seq(commentText))
+            case CodeComment(lines) =>
+              val newLines = lines :+ commentText
+              comments.remove(comments.length-1)
+              comments += CodeComment(newLines)
+          }
+        }
+
+      }
+
+    })
+
+    Doc(comments)
+
+  }
 
   def parens[T](inner: Parser[T]): Parser[T] = surround("(", ")", inner)
   def typeList[T](inner: Parser[T]): Parser[Seq[T]] = surround("<", ">", rep1sepend(inner, ",")) | success(Seq.empty)
diff --git a/test-suite/djinni/client_interface.djinni b/test-suite/djinni/client_interface.djinni
index 10c5e8657..2d1a13e05 100644
--- a/test-suite/djinni/client_interface.djinni
+++ b/test-suite/djinni/client_interface.djinni
@@ -1,17 +1,20 @@
-# Record returned by a client
+// Record returned by a client
 client_returned_record = record {
     record_id: i64;
     content: string;
     misc: optional<string>;
 }
 
-# Client interface
+// Client interface
 client_interface = interface +j +o {
+    // Testing code comments before documentation comments
     # Returns record of given string
     get_record(record_id: i64, utf8string: string, misc: optional<string>): client_returned_record;
 	identifier_check(data: binary, r: i32, jret: i64): f64;
     return_str(): string;
 
+    # Testing documentation comments before code comments
+    // This method takes an interface
     meth_taking_interface(i: client_interface): string;
     meth_taking_optional_interface(i: optional<client_interface>): string;
 }
@@ -19,7 +22,20 @@ client_interface = interface +j +o {
 reverse_client_interface = interface +c {
     const return_str(): string;
 
+    // Testing code comments before documentation comments
+    // with multiple lines
+    // and another line
+    # Testing documentation comments after code comments
+    # with multiple lines
+    # and another line
     meth_taking_interface(i: reverse_client_interface): string;
+
+    # Testing documentation comments before code comments
+    # with multiple lines
+    # and another line
+    // Testing code comments after documentation comments
+    // with multiple lines
+    // and another line
     meth_taking_optional_interface(i: optional<reverse_client_interface>): string;
 
     static create(): reverse_client_interface;
diff --git a/test-suite/djinni/constant_enum.djinni b/test-suite/djinni/constant_enum.djinni
index a7c57cb3c..0ff4b23c3 100644
--- a/test-suite/djinni/constant_enum.djinni
+++ b/test-suite/djinni/constant_enum.djinni
@@ -1,4 +1,4 @@
-# enum for use in constants
+// enum for use in constants
 constant_enum = enum {
     some_value;
     some_other_value;
diff --git a/test-suite/djinni/constants.djinni b/test-suite/djinni/constants.djinni
index 3222e8618..65b1cc208 100644
--- a/test-suite/djinni/constants.djinni
+++ b/test-suite/djinni/constants.djinni
@@ -8,10 +8,14 @@ constant_record = record {
 constants = record {
     # bool_constant has documentation.
     const bool_constant: bool = true;
+    // i8_constant has a comment
     const i8_constant: i8 = 1;
     const i16_constant: i16 = 2;
     const i32_constant: i32 = 3;
     const i64_constant: i64 = 4;
+    // f64_constant has a long comment.
+    // (Second line of multi-line comment.
+    //   Indented third line of multi-line comment.)
     const f32_constant: f32 = 5.0;
     # f64_constant has long documentation.
     # (Second line of multi-line documentation.
@@ -39,7 +43,7 @@ constants = record {
     };
 
     # No support for null optional constants
-    # No support for optional constant records
+    // No support for optional constant records
     # No support for constant binary, list, set, map
 
     const dummy: bool = false;
@@ -79,9 +83,9 @@ constants_interface = interface +c {
         some_string = string_constant
     };
 
-    # No support for null optional constants
+    // No support for null optional constants
     # No support for optional constant records
-    # No support for constant binary, list, set, map
+    // No support for constant binary, list, set, map
 
     dummy();
 }
diff --git a/test-suite/djinni/enum.djinni b/test-suite/djinni/enum.djinni
index ce4061d88..4fc107905 100644
--- a/test-suite/djinni/enum.djinni
+++ b/test-suite/djinni/enum.djinni
@@ -2,6 +2,9 @@ color = enum {
 	red;
 	orange;
 	yellow;
+	// "It is customary to list indigo as a color lying between blue and violet, but it has
+	// never seemed to me that indigo is worth the dignity of being considered a separate
+	// color. To my eyes it seems merely deep blue." --Isaac Asimov
 	green;
 	blue;
 	# "It is customary to list indigo as a color lying between blue and violet, but it has
diff --git a/test-suite/djinni/multiple_inheritance.djinni b/test-suite/djinni/multiple_inheritance.djinni
index cc121f778..163539a1d 100644
--- a/test-suite/djinni/multiple_inheritance.djinni
+++ b/test-suite/djinni/multiple_inheritance.djinni
@@ -3,7 +3,7 @@ first_listener = interface +o {
     first();
 }
 
-# Used for ObjC multiple inheritance tests
+// Used for ObjC multiple inheritance tests
 second_listener = interface +o {
     second();
 }
@@ -25,7 +25,7 @@ return_one = interface +c {
     return_one(): i8;
 }
 
-# Used for C++ multiple inheritance tests
+// Used for C++ multiple inheritance tests
 return_two = interface +c {
     static get_instance(): return_two;
     return_two(): i8;
diff --git a/test-suite/djinni/yaml-test.djinni b/test-suite/djinni/yaml-test.djinni
index 5c11e1a21..ad5b9f22b 100644
--- a/test-suite/djinni/yaml-test.djinni
+++ b/test-suite/djinni/yaml-test.djinni
@@ -8,6 +8,8 @@ extern_record_with_derivings = record
 	e: test_color;
 } deriving(eq, ord)
 
+// This file tests YAML dumped by Djinni can be parsed back in
+
 extern_interface_1 = interface +c
 {
 	foo(i: test_client_interface): test_client_returned_record;
diff --git a/test-suite/generated-src/cpp/client_interface.hpp b/test-suite/generated-src/cpp/client_interface.hpp
index 0b35234cd..5d7be1319 100644
--- a/test-suite/generated-src/cpp/client_interface.hpp
+++ b/test-suite/generated-src/cpp/client_interface.hpp
@@ -13,11 +13,12 @@ namespace testsuite {
 
 struct ClientReturnedRecord;
 
-/** Client interface */
+// Client interface
 class ClientInterface {
 public:
     virtual ~ClientInterface() {}
 
+    // Testing code comments before documentation comments
     /** Returns record of given string */
     virtual ClientReturnedRecord get_record(int64_t record_id, const std::string & utf8string, const std::experimental::optional<std::string> & misc) = 0;
 
@@ -25,6 +26,8 @@ class ClientInterface {
 
     virtual std::string return_str() = 0;
 
+    /** Testing documentation comments before code comments */
+    // This method takes an interface
     virtual std::string meth_taking_interface(const std::shared_ptr<ClientInterface> & i) = 0;
 
     virtual std::string meth_taking_optional_interface(const std::shared_ptr<ClientInterface> & i) = 0;
diff --git a/test-suite/generated-src/cpp/client_returned_record.hpp b/test-suite/generated-src/cpp/client_returned_record.hpp
index 4252095e5..84ff4553a 100644
--- a/test-suite/generated-src/cpp/client_returned_record.hpp
+++ b/test-suite/generated-src/cpp/client_returned_record.hpp
@@ -10,7 +10,7 @@
 
 namespace testsuite {
 
-/** Record returned by a client */
+// Record returned by a client
 struct ClientReturnedRecord final {
     int64_t record_id;
     std::string content;
diff --git a/test-suite/generated-src/cpp/color.hpp b/test-suite/generated-src/cpp/color.hpp
index b0d2d7397..2856ec555 100644
--- a/test-suite/generated-src/cpp/color.hpp
+++ b/test-suite/generated-src/cpp/color.hpp
@@ -11,6 +11,9 @@ enum class color : int {
     RED,
     ORANGE,
     YELLOW,
+    // "It is customary to list indigo as a color lying between blue and violet, but it has
+    // never seemed to me that indigo is worth the dignity of being considered a separate
+    // color. To my eyes it seems merely deep blue." --Isaac Asimov
     GREEN,
     BLUE,
     /**
diff --git a/test-suite/generated-src/cpp/constants.hpp b/test-suite/generated-src/cpp/constants.hpp
index eac9e97f6..fbe78678a 100644
--- a/test-suite/generated-src/cpp/constants.hpp
+++ b/test-suite/generated-src/cpp/constants.hpp
@@ -17,6 +17,7 @@ struct Constants final {
     /** bool_constant has documentation. */
     static constexpr bool BOOL_CONSTANT = true;
 
+    // i8_constant has a comment
     static constexpr int8_t I8_CONSTANT = 1;
 
     static constexpr int16_t I16_CONSTANT = 2;
@@ -25,6 +26,9 @@ struct Constants final {
 
     static constexpr int64_t I64_CONSTANT = 4;
 
+    // f64_constant has a long comment.
+    // (Second line of multi-line comment.
+    //   Indented third line of multi-line comment.)
     static constexpr float F32_CONSTANT = 5.0f;
 
     /**
@@ -60,11 +64,9 @@ struct Constants final {
 
     static ConstantRecord const OBJECT_CONSTANT;
 
-    /**
-     * No support for null optional constants
-     * No support for optional constant records
-     * No support for constant binary, list, set, map
-     */
+    /** No support for null optional constants */
+    // No support for optional constant records
+    /** No support for constant binary, list, set, map */
     static constexpr bool DUMMY = false;
 };
 
diff --git a/test-suite/generated-src/cpp/constants_interface.hpp b/test-suite/generated-src/cpp/constants_interface.hpp
index c73189728..80ae5596b 100644
--- a/test-suite/generated-src/cpp/constants_interface.hpp
+++ b/test-suite/generated-src/cpp/constants_interface.hpp
@@ -62,11 +62,9 @@ class ConstantsInterface {
 
     static ConstantRecord const OBJECT_CONSTANT;
 
-    /**
-     * No support for null optional constants
-     * No support for optional constant records
-     * No support for constant binary, list, set, map
-     */
+    // No support for null optional constants
+    /** No support for optional constant records */
+    // No support for constant binary, list, set, map
     virtual void dummy() = 0;
 };
 
diff --git a/test-suite/generated-src/cpp/extern_interface_1.hpp b/test-suite/generated-src/cpp/extern_interface_1.hpp
index 5c207ff3e..87cd0d148 100644
--- a/test-suite/generated-src/cpp/extern_interface_1.hpp
+++ b/test-suite/generated-src/cpp/extern_interface_1.hpp
@@ -7,6 +7,7 @@
 #include "client_returned_record.hpp"
 #include <memory>
 
+// This file tests YAML dumped by Djinni can be parsed back in
 class ExternInterface1 {
 public:
     virtual ~ExternInterface1() {}
diff --git a/test-suite/generated-src/cpp/return_two.hpp b/test-suite/generated-src/cpp/return_two.hpp
index abb41f9f0..ae50d8545 100644
--- a/test-suite/generated-src/cpp/return_two.hpp
+++ b/test-suite/generated-src/cpp/return_two.hpp
@@ -8,7 +8,7 @@
 
 namespace testsuite {
 
-/** Used for C++ multiple inheritance tests */
+// Used for C++ multiple inheritance tests
 class ReturnTwo {
 public:
     virtual ~ReturnTwo() {}
diff --git a/test-suite/generated-src/cpp/reverse_client_interface.hpp b/test-suite/generated-src/cpp/reverse_client_interface.hpp
index 955b912a5..40c514ba5 100644
--- a/test-suite/generated-src/cpp/reverse_client_interface.hpp
+++ b/test-suite/generated-src/cpp/reverse_client_interface.hpp
@@ -15,8 +15,24 @@ class ReverseClientInterface {
 
     virtual std::string return_str() const = 0;
 
+    // Testing code comments before documentation comments
+    // with multiple lines
+    // and another line
+    /**
+     * Testing documentation comments after code comments
+     * with multiple lines
+     * and another line
+     */
     virtual std::string meth_taking_interface(const std::shared_ptr<ReverseClientInterface> & i) = 0;
 
+    /**
+     * Testing documentation comments before code comments
+     * with multiple lines
+     * and another line
+     */
+    // Testing code comments after documentation comments
+    // with multiple lines
+    // and another line
     virtual std::string meth_taking_optional_interface(const std::shared_ptr<ReverseClientInterface> & i) = 0;
 
     static std::shared_ptr<ReverseClientInterface> create();
diff --git a/test-suite/generated-src/cpp/second_listener.hpp b/test-suite/generated-src/cpp/second_listener.hpp
index 10ed57b81..2c1e254f3 100644
--- a/test-suite/generated-src/cpp/second_listener.hpp
+++ b/test-suite/generated-src/cpp/second_listener.hpp
@@ -5,7 +5,7 @@
 
 namespace testsuite {
 
-/** Used for ObjC multiple inheritance tests */
+// Used for ObjC multiple inheritance tests
 class SecondListener {
 public:
     virtual ~SecondListener() {}
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ClientInterface.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ClientInterface.java
index b77eed268..ee8040532 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ClientInterface.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ClientInterface.java
@@ -6,8 +6,9 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
-/** Client interface */
+// Client interface
 public interface ClientInterface {
+    // Testing code comments before documentation comments
     /** Returns record of given string */
     @Nonnull
     public ClientReturnedRecord getRecord(long recordId, @Nonnull String utf8string, @CheckForNull String misc);
@@ -17,6 +18,8 @@ public interface ClientInterface {
     @Nonnull
     public String returnStr();
 
+    /** Testing documentation comments before code comments */
+    // This method takes an interface
     @Nonnull
     public String methTakingInterface(@CheckForNull ClientInterface i);
 
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ClientReturnedRecord.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ClientReturnedRecord.java
index 2e51ae4b9..11b85e2e9 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ClientReturnedRecord.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ClientReturnedRecord.java
@@ -6,7 +6,7 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
-/** Record returned by a client */
+// Record returned by a client
 public class ClientReturnedRecord {
 
 
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/Color.java b/test-suite/generated-src/java/com/dropbox/djinni/test/Color.java
index 0f643808b..c36219f79 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/Color.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/Color.java
@@ -10,6 +10,9 @@ public enum Color {
     RED,
     ORANGE,
     YELLOW,
+    // "It is customary to list indigo as a color lying between blue and violet, but it has
+    // never seemed to me that indigo is worth the dignity of being considered a separate
+    // color. To my eyes it seems merely deep blue." --Isaac Asimov
     GREEN,
     BLUE,
     /**
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantEnum.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantEnum.java
index 89782b089..e9daeff0d 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantEnum.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantEnum.java
@@ -6,7 +6,7 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
-/** enum for use in constants */
+// enum for use in constants
 public enum ConstantEnum {
     SOME_VALUE,
     SOME_OTHER_VALUE,
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/Constants.java b/test-suite/generated-src/java/com/dropbox/djinni/test/Constants.java
index 079d8ecca..be69f15bc 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/Constants.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/Constants.java
@@ -12,6 +12,7 @@ public class Constants {
     /** bool_constant has documentation. */
     public static final boolean BOOL_CONSTANT = true;
 
+    // i8_constant has a comment
     public static final byte I8_CONSTANT = 1;
 
     public static final short I16_CONSTANT = 2;
@@ -20,6 +21,9 @@ public class Constants {
 
     public static final long I64_CONSTANT = 4l;
 
+    // f64_constant has a long comment.
+    // (Second line of multi-line comment.
+    //   Indented third line of multi-line comment.)
     public static final float F32_CONSTANT = 5.0f;
 
     /**
@@ -67,11 +71,9 @@ public class Constants {
         I32_CONSTANT /* mSomeInteger */ ,
         STRING_CONSTANT /* mSomeString */ );
 
-    /**
-     * No support for null optional constants
-     * No support for optional constant records
-     * No support for constant binary, list, set, map
-     */
+    /** No support for null optional constants */
+    // No support for optional constant records
+    /** No support for constant binary, list, set, map */
     public static final boolean DUMMY = false;
 
 
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantsInterface.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantsInterface.java
index 03a043aae..476d96dec 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantsInterface.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ConstantsInterface.java
@@ -67,11 +67,9 @@ public interface ConstantsInterface {
         I32_CONSTANT /* mSomeInteger */ ,
         STRING_CONSTANT /* mSomeString */ );
 
-    /**
-     * No support for null optional constants
-     * No support for optional constant records
-     * No support for constant binary, list, set, map
-     */
+    // No support for null optional constants
+    /** No support for optional constant records */
+    // No support for constant binary, list, set, map
     public void dummy();
 
     static final class CppProxy implements ConstantsInterface
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ExternInterface1.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ExternInterface1.java
index 5af1efcc9..4fc8f510c 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ExternInterface1.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ExternInterface1.java
@@ -5,6 +5,7 @@
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
+// This file tests YAML dumped by Djinni can be parsed back in
 public interface ExternInterface1 {
     public com.dropbox.djinni.test.ClientReturnedRecord foo(com.dropbox.djinni.test.ClientInterface i);
 
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ReturnTwo.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ReturnTwo.java
index 580e6a73f..5585106ce 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ReturnTwo.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ReturnTwo.java
@@ -7,7 +7,7 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
-/** Used for C++ multiple inheritance tests */
+// Used for C++ multiple inheritance tests
 public interface ReturnTwo {
     public byte returnTwo();
 
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/ReverseClientInterface.java b/test-suite/generated-src/java/com/dropbox/djinni/test/ReverseClientInterface.java
index 4187bf6f0..eaee69fac 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/ReverseClientInterface.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/ReverseClientInterface.java
@@ -11,9 +11,25 @@ public interface ReverseClientInterface {
     @Nonnull
     public String returnStr();
 
+    // Testing code comments before documentation comments
+    // with multiple lines
+    // and another line
+    /**
+     * Testing documentation comments after code comments
+     * with multiple lines
+     * and another line
+     */
     @Nonnull
     public String methTakingInterface(@CheckForNull ReverseClientInterface i);
 
+    /**
+     * Testing documentation comments before code comments
+     * with multiple lines
+     * and another line
+     */
+    // Testing code comments after documentation comments
+    // with multiple lines
+    // and another line
     @Nonnull
     public String methTakingOptionalInterface(@CheckForNull ReverseClientInterface i);
 
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java b/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java
index 9bcd6dd3a..de66acb90 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java
@@ -6,7 +6,7 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
-/** Used for ObjC multiple inheritance tests */
+// Used for ObjC multiple inheritance tests
 public interface SecondListener {
     public void second();
 }
diff --git a/test-suite/generated-src/objc/DBClientInterface.h b/test-suite/generated-src/objc/DBClientInterface.h
index 73c7a883f..d6a136e50 100644
--- a/test-suite/generated-src/objc/DBClientInterface.h
+++ b/test-suite/generated-src/objc/DBClientInterface.h
@@ -6,9 +6,10 @@
 @protocol DBClientInterface;
 
 
-/** Client interface */
+// Client interface
 @protocol DBClientInterface
 
+// Testing code comments before documentation comments
 /** Returns record of given string */
 - (nonnull DBClientReturnedRecord *)getRecord:(int64_t)recordId
                                    utf8string:(nonnull NSString *)utf8string
@@ -20,6 +21,8 @@
 
 - (nonnull NSString *)returnStr;
 
+/** Testing documentation comments before code comments */
+// This method takes an interface
 - (nonnull NSString *)methTakingInterface:(nullable id<DBClientInterface>)i;
 
 - (nonnull NSString *)methTakingOptionalInterface:(nullable id<DBClientInterface>)i;
diff --git a/test-suite/generated-src/objc/DBClientReturnedRecord.h b/test-suite/generated-src/objc/DBClientReturnedRecord.h
index cbadd28d9..0a66e3f3b 100644
--- a/test-suite/generated-src/objc/DBClientReturnedRecord.h
+++ b/test-suite/generated-src/objc/DBClientReturnedRecord.h
@@ -3,7 +3,7 @@
 
 #import <Foundation/Foundation.h>
 
-/** Record returned by a client */
+// Record returned by a client
 @interface DBClientReturnedRecord : NSObject
 - (nonnull instancetype)initWithRecordId:(int64_t)recordId
                                  content:(nonnull NSString *)content
diff --git a/test-suite/generated-src/objc/DBColor.h b/test-suite/generated-src/objc/DBColor.h
index f03f45bb5..245b2fc7c 100644
--- a/test-suite/generated-src/objc/DBColor.h
+++ b/test-suite/generated-src/objc/DBColor.h
@@ -8,6 +8,9 @@ typedef NS_ENUM(NSInteger, DBColor)
     DBColorRed,
     DBColorOrange,
     DBColorYellow,
+    // "It is customary to list indigo as a color lying between blue and violet, but it has
+    // never seemed to me that indigo is worth the dignity of being considered a separate
+    // color. To my eyes it seems merely deep blue." --Isaac Asimov
     DBColorGreen,
     DBColorBlue,
     /**
diff --git a/test-suite/generated-src/objc/DBConstantEnum.h b/test-suite/generated-src/objc/DBConstantEnum.h
index 6b318dc25..39be26a3f 100644
--- a/test-suite/generated-src/objc/DBConstantEnum.h
+++ b/test-suite/generated-src/objc/DBConstantEnum.h
@@ -3,7 +3,7 @@
 
 #import <Foundation/Foundation.h>
 
-/** enum for use in constants */
+// enum for use in constants
 typedef NS_ENUM(NSInteger, DBConstantEnum)
 {
     DBConstantEnumSomeValue,
diff --git a/test-suite/generated-src/objc/DBConstants.h b/test-suite/generated-src/objc/DBConstants.h
index f29696d84..1892702e8 100644
--- a/test-suite/generated-src/objc/DBConstants.h
+++ b/test-suite/generated-src/objc/DBConstants.h
@@ -27,10 +27,14 @@
 
 /** bool_constant has documentation. */
 extern BOOL const DBConstantsBoolConstant;
+// i8_constant has a comment
 extern int8_t const DBConstantsI8Constant;
 extern int16_t const DBConstantsI16Constant;
 extern int32_t const DBConstantsI32Constant;
 extern int64_t const DBConstantsI64Constant;
+// f64_constant has a long comment.
+// (Second line of multi-line comment.
+//   Indented third line of multi-line comment.)
 extern float const DBConstantsF32Constant;
 /**
  * f64_constant has long documentation.
@@ -40,9 +44,7 @@ extern float const DBConstantsF32Constant;
 extern double const DBConstantsF64Constant;
 extern NSString * __nonnull const DBConstantsStringConstant;
 extern NSString * __nullable const DBConstantsOptStringConstant;
-/**
- * No support for null optional constants
- * No support for optional constant records
- * No support for constant binary, list, set, map
- */
+/** No support for null optional constants */
+// No support for optional constant records
+/** No support for constant binary, list, set, map */
 extern BOOL const DBConstantsDummy;
diff --git a/test-suite/generated-src/objc/DBConstantsInterface.h b/test-suite/generated-src/objc/DBConstantsInterface.h
index c8c86ca24..d0f5aef74 100644
--- a/test-suite/generated-src/objc/DBConstantsInterface.h
+++ b/test-suite/generated-src/objc/DBConstantsInterface.h
@@ -23,11 +23,9 @@ extern NSString * __nullable const DBConstantsInterfaceOptStringConstant;
 /** Interface containing constants */
 @interface DBConstantsInterface : NSObject
 
-/**
- * No support for null optional constants
- * No support for optional constant records
- * No support for constant binary, list, set, map
- */
+// No support for null optional constants
+/** No support for optional constant records */
+// No support for constant binary, list, set, map
 - (void)dummy;
 
 + (NSNumber * __nullable)optBoolConstant;
diff --git a/test-suite/generated-src/objc/DBExternInterface1.h b/test-suite/generated-src/objc/DBExternInterface1.h
index 25fac69cf..047bf85fe 100644
--- a/test-suite/generated-src/objc/DBExternInterface1.h
+++ b/test-suite/generated-src/objc/DBExternInterface1.h
@@ -6,6 +6,7 @@
 #import <Foundation/Foundation.h>
 
 
+// This file tests YAML dumped by Djinni can be parsed back in
 @interface DBExternInterface1 : NSObject
 
 - (nonnull DBClientReturnedRecord *)foo:(nullable id<DBClientInterface>)i;
diff --git a/test-suite/generated-src/objc/DBReturnTwo.h b/test-suite/generated-src/objc/DBReturnTwo.h
index 2e3438950..5014ee28f 100644
--- a/test-suite/generated-src/objc/DBReturnTwo.h
+++ b/test-suite/generated-src/objc/DBReturnTwo.h
@@ -5,7 +5,7 @@
 @class DBReturnTwo;
 
 
-/** Used for C++ multiple inheritance tests */
+// Used for C++ multiple inheritance tests
 @interface DBReturnTwo : NSObject
 
 + (nullable DBReturnTwo *)getInstance;
diff --git a/test-suite/generated-src/objc/DBReverseClientInterface.h b/test-suite/generated-src/objc/DBReverseClientInterface.h
index 057614e31..c4abf12c8 100644
--- a/test-suite/generated-src/objc/DBReverseClientInterface.h
+++ b/test-suite/generated-src/objc/DBReverseClientInterface.h
@@ -9,8 +9,24 @@
 
 - (nonnull NSString *)returnStr;
 
+// Testing code comments before documentation comments
+// with multiple lines
+// and another line
+/**
+ * Testing documentation comments after code comments
+ * with multiple lines
+ * and another line
+ */
 - (nonnull NSString *)methTakingInterface:(nullable DBReverseClientInterface *)i;
 
+/**
+ * Testing documentation comments before code comments
+ * with multiple lines
+ * and another line
+ */
+// Testing code comments after documentation comments
+// with multiple lines
+// and another line
 - (nonnull NSString *)methTakingOptionalInterface:(nullable DBReverseClientInterface *)i;
 
 + (nullable DBReverseClientInterface *)create;
diff --git a/test-suite/generated-src/objc/DBSecondListener.h b/test-suite/generated-src/objc/DBSecondListener.h
index 28a03a42d..e93e99e0a 100644
--- a/test-suite/generated-src/objc/DBSecondListener.h
+++ b/test-suite/generated-src/objc/DBSecondListener.h
@@ -4,7 +4,7 @@
 #import <Foundation/Foundation.h>
 
 
-/** Used for ObjC multiple inheritance tests */
+// Used for ObjC multiple inheritance tests
 @protocol DBSecondListener
 
 - (void)second;

From 875bbe24ce92de99551869b5596b8c5f93600558 Mon Sep 17 00:00:00 2001
From: Xianwen Chen <xianwen@dropbox.com>
Date: Wed, 18 Jul 2018 12:53:02 -0700
Subject: [PATCH 5/5] Make doc comment compatible with Python branch

---
 src/source/PythonGenerator.scala              | 33 +++++++++----------
 .../generated-src/cpp/second_listener.hpp     |  2 +-
 .../dropbox/djinni/test/SecondListener.java   |  2 +-
 .../generated-src/objc/DBSecondListener.h     |  2 +-
 .../generated-src/pycpp/client_interface.hpp  |  5 ++-
 .../pycpp/client_returned_record.hpp          |  2 +-
 test-suite/generated-src/pycpp/color.hpp      |  3 ++
 test-suite/generated-src/pycpp/constants.cpp  | 16 ++++-----
 test-suite/generated-src/pycpp/constants.hpp  | 12 ++++---
 .../pycpp/constants_interface.cpp             | 14 ++++----
 .../pycpp/constants_interface.hpp             |  8 ++---
 .../generated-src/pycpp/foo_constants.cpp     | 14 ++++----
 .../pycpp/foo_constants_interface.cpp         | 14 ++++----
 test-suite/generated-src/pycpp/return_two.hpp |  2 +-
 .../pycpp/reverse_client_interface.hpp        | 16 +++++++++
 .../generated-src/pycpp/second_listener.hpp   |  2 +-
 .../generated-src/python/client_interface.py  |  9 ++++-
 test-suite/generated-src/python/color.py      |  5 +++
 test-suite/generated-src/python/constants.py  |  6 ++--
 .../python/reverse_client_interface.py        | 16 +++++++++
 20 files changed, 117 insertions(+), 66 deletions(-)

diff --git a/src/source/PythonGenerator.scala b/src/source/PythonGenerator.scala
index 7f84d6162..0725c2e7e 100644
--- a/src/source/PythonGenerator.scala
+++ b/src/source/PythonGenerator.scala
@@ -41,19 +41,19 @@ class PythonGenerator(spec: Spec) extends Generator(spec) {
 
   // Override since Python doesn't share the C-style comment syntax.
   override def writeDoc(w: IndentWriter, doc: Doc) {
-    doc.lines.foreach(l => w.wl(s"#$l"))
+    doc.comments.foreach(comment => comment.lines.foreach(l => w.wl(s"#$l")) )
   }
 
   // Use docstrings rather than comments when available.
   def writeDocString(w: IndentWriter, doc: Doc, docLists: Seq[IndentWriter => Unit] = Seq()): Boolean = {
-    if (doc.lines.isEmpty && docLists.isEmpty) {
+    if (doc.comments.isEmpty && docLists.isEmpty) {
       return false
     }
-    if (doc.lines.length == 1 && docLists.isEmpty) {
-      w.wl(s"""\"\"\"${doc.lines.head} \"\"\"""")
+    if (doc.comments.length == 1 && doc.comments.head.lines.length == 1 && docLists.isEmpty) {
+      w.wl(s"""\"\"\"${doc.comments.head.lines.head} \"\"\"""")
     } else {
       w.wl("\"\"\"")
-      doc.lines.foreach (l => w.wl(s"$l"))
+      doc.comments.foreach(comment => comment.lines.foreach(l => w.wl(s"$l")))
       docLists.foreach (docList => docList(w))
       w.wl("\"\"\"")
     }
@@ -67,34 +67,33 @@ class PythonGenerator(spec: Spec) extends Generator(spec) {
     }
   }
 
-  def writeDocListItem(w: IndentWriter, name: String, lines: Seq[String]): Unit = {
-    if (lines.isEmpty) {
+  def writeDocListItem(w: IndentWriter, name: String, comments: Seq[Comment]): Unit = {
+    if (comments.isEmpty) {
       w.wl(s"${name}")
     } else {
-      w.wl(s"${name}: ${lines.head.trim}")
+      w.wl(s"${name}: ${comments.head.lines.head.trim}")
       w.nested {
-        lines.tail.foreach (l => {
-          w.wl(l)
-        })
+        comments.head.lines.tail.foreach (l => w.wl(l))
+        comments.tail.foreach (comment => comment.lines.foreach (l => w.wl(l)) )
       }
     }
   }
 
   def writeDocConstantsList(w: IndentWriter, consts: Seq[Const]): Unit = {
     writeDocList(w, "Constants", { w => consts.foreach (c => {
-      writeDocListItem(w, idPython.const(c.ident), c.doc.lines)
+      writeDocListItem(w, idPython.const(c.ident), c.doc.comments)
     })})
   }
 
   def writeDocFieldsList(w: IndentWriter, fields: Seq[Field]): Unit = {
     writeDocList(w, "Fields", { w => fields.foreach (f => {
-      writeDocListItem(w, idPython.field(f.ident), f.doc.lines)
+      writeDocListItem(w, idPython.field(f.ident), f.doc.comments)
     })})
   }
 
   def writeDocEnumOptionsList(w: IndentWriter, options: Seq[Enum.Option]): Unit = {
     writeDocList(w, "Members", { w => options.foreach (o => {
-      writeDocListItem(w, idPython.enum(o.ident), o.doc.lines)
+      writeDocListItem(w, idPython.enum(o.ident), o.doc.comments)
     })})
   }
 
@@ -800,7 +799,7 @@ class PythonGenerator(spec: Spec) extends Generator(spec) {
     writePythonFile(ident, origin, refs.python, true, w => {
       // Asbtract Class Definition
       w.wl("class " + pythonClass + "(with_metaclass(ABCMeta)):").nested {
-        val docConsts = if (!i.consts.exists(!_.doc.lines.isEmpty)) Seq() else Seq({
+        val docConsts = if (!i.consts.exists(!_.doc.comments.isEmpty)) Seq() else Seq({
           w: IndentWriter => writeDocConstantsList(w, i.consts)
         })
         if (writeDocString(w, doc, docConsts)) { w.wl }
@@ -993,8 +992,8 @@ class PythonGenerator(spec: Spec) extends Generator(spec) {
       // Record Definition
       w.wl("class " + recordClassName + (if(r.ext.py) "Base" else "") + ":").nested {
         var docLists = mutable.ArrayBuffer[IndentWriter => Unit]()
-        if (r.fields.exists(!_.doc.lines.isEmpty)) docLists += { w: IndentWriter => writeDocFieldsList(w, r.fields)}
-        if (r.consts.exists(!_.doc.lines.isEmpty)) docLists += { w: IndentWriter => writeDocConstantsList(w, r.consts)}
+        if (r.fields.exists(!_.doc.comments.isEmpty)) docLists += { w: IndentWriter => writeDocFieldsList(w, r.fields)}
+        if (r.consts.exists(!_.doc.comments.isEmpty)) docLists += { w: IndentWriter => writeDocConstantsList(w, r.consts)}
         if (writeDocString(w, doc, docLists)) { w.wl }
 
 
diff --git a/test-suite/generated-src/cpp/second_listener.hpp b/test-suite/generated-src/cpp/second_listener.hpp
index 891774a1d..cbc2eab52 100644
--- a/test-suite/generated-src/cpp/second_listener.hpp
+++ b/test-suite/generated-src/cpp/second_listener.hpp
@@ -5,7 +5,7 @@
 
 namespace testsuite {
 
-/** Used for non-C++ multiple inheritance tests */
+// Used for non-C++ multiple inheritance tests
 class SecondListener {
 public:
     virtual ~SecondListener() {}
diff --git a/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java b/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java
index 7e9762506..953324a07 100644
--- a/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java
+++ b/test-suite/generated-src/java/com/dropbox/djinni/test/SecondListener.java
@@ -6,7 +6,7 @@
 import javax.annotation.CheckForNull;
 import javax.annotation.Nonnull;
 
-/** Used for non-C++ multiple inheritance tests */
+// Used for non-C++ multiple inheritance tests
 public interface SecondListener {
     public void second();
 }
diff --git a/test-suite/generated-src/objc/DBSecondListener.h b/test-suite/generated-src/objc/DBSecondListener.h
index a090e50db..b5f0b76cc 100644
--- a/test-suite/generated-src/objc/DBSecondListener.h
+++ b/test-suite/generated-src/objc/DBSecondListener.h
@@ -4,7 +4,7 @@
 #import <Foundation/Foundation.h>
 
 
-/** Used for non-C++ multiple inheritance tests */
+// Used for non-C++ multiple inheritance tests
 @protocol DBSecondListener
 
 - (void)second;
diff --git a/test-suite/generated-src/pycpp/client_interface.hpp b/test-suite/generated-src/pycpp/client_interface.hpp
index fa2c84410..377ab580c 100644
--- a/test-suite/generated-src/pycpp/client_interface.hpp
+++ b/test-suite/generated-src/pycpp/client_interface.hpp
@@ -13,11 +13,12 @@ namespace testsuite {
 
 struct ClientReturnedRecord;
 
-/** Client interface */
+// Client interface
 class ClientInterface {
 public:
     virtual ~ClientInterface() {}
 
+    // Testing code comments before documentation comments
     /** Returns record of given string */
     virtual ClientReturnedRecord get_record(int64_t record_id, const std::string & utf8string, const std::experimental::optional<std::string> & misc) = 0;
 
@@ -25,6 +26,8 @@ class ClientInterface {
 
     virtual std::string return_str() = 0;
 
+    /** Testing documentation comments before code comments */
+    // This method takes an interface
     virtual std::string meth_taking_interface(const std::shared_ptr<ClientInterface> & i) = 0;
 
     virtual std::string meth_taking_optional_interface(const std::shared_ptr<ClientInterface> & i) = 0;
diff --git a/test-suite/generated-src/pycpp/client_returned_record.hpp b/test-suite/generated-src/pycpp/client_returned_record.hpp
index ac18574e8..1b937fbeb 100644
--- a/test-suite/generated-src/pycpp/client_returned_record.hpp
+++ b/test-suite/generated-src/pycpp/client_returned_record.hpp
@@ -10,7 +10,7 @@
 
 namespace testsuite {
 
-/** Record returned by a client */
+// Record returned by a client
 struct ClientReturnedRecord final {
     int64_t record_id;
     std::string content;
diff --git a/test-suite/generated-src/pycpp/color.hpp b/test-suite/generated-src/pycpp/color.hpp
index b0d2d7397..2856ec555 100644
--- a/test-suite/generated-src/pycpp/color.hpp
+++ b/test-suite/generated-src/pycpp/color.hpp
@@ -11,6 +11,9 @@ enum class color : int {
     RED,
     ORANGE,
     YELLOW,
+    // "It is customary to list indigo as a color lying between blue and violet, but it has
+    // never seemed to me that indigo is worth the dignity of being considered a separate
+    // color. To my eyes it seems merely deep blue." --Isaac Asimov
     GREEN,
     BLUE,
     /**
diff --git a/test-suite/generated-src/pycpp/constants.cpp b/test-suite/generated-src/pycpp/constants.cpp
index c9fcafb41..d21ba16c2 100644
--- a/test-suite/generated-src/pycpp/constants.cpp
+++ b/test-suite/generated-src/pycpp/constants.cpp
@@ -5,19 +5,19 @@
 
 namespace testsuite {
 
-bool const Constants::BOOL_CONSTANT;
+bool constexpr Constants::BOOL_CONSTANT;
 
-int8_t const Constants::I8_CONSTANT;
+int8_t constexpr Constants::I8_CONSTANT;
 
-int16_t const Constants::I16_CONSTANT;
+int16_t constexpr Constants::I16_CONSTANT;
 
-int32_t const Constants::I32_CONSTANT;
+int32_t constexpr Constants::I32_CONSTANT;
 
-int64_t const Constants::I64_CONSTANT;
+int64_t constexpr Constants::I64_CONSTANT;
 
-float const Constants::F32_CONSTANT;
+float constexpr Constants::F32_CONSTANT;
 
-double const Constants::F64_CONSTANT;
+double constexpr Constants::F64_CONSTANT;
 
 std::experimental::optional<bool> const Constants::OPT_BOOL_CONSTANT = true;
 
@@ -41,6 +41,6 @@ ConstantRecord const Constants::OBJECT_CONSTANT = ConstantRecord(
     Constants::I32_CONSTANT /* some_integer */ ,
     Constants::STRING_CONSTANT /* some_string */ );
 
-bool const Constants::DUMMY;
+bool constexpr Constants::DUMMY;
 
 }  // namespace testsuite
diff --git a/test-suite/generated-src/pycpp/constants.hpp b/test-suite/generated-src/pycpp/constants.hpp
index 1ca1cf6cb..ba265e971 100644
--- a/test-suite/generated-src/pycpp/constants.hpp
+++ b/test-suite/generated-src/pycpp/constants.hpp
@@ -17,6 +17,7 @@ struct Constants final {
     /** bool_constant has documentation. */
     static constexpr bool BOOL_CONSTANT = true;
 
+    // i8_constant has a comment
     static constexpr int8_t I8_CONSTANT = 1;
 
     static constexpr int16_t I16_CONSTANT = 2;
@@ -25,6 +26,9 @@ struct Constants final {
 
     static constexpr int64_t I64_CONSTANT = 4;
 
+    // f64_constant has a long comment.
+    // (Second line of multi-line comment.
+    //   Indented third line of multi-line comment.)
     static constexpr float F32_CONSTANT = 5.0f;
 
     /**
@@ -60,11 +64,9 @@ struct Constants final {
 
     static ConstantRecord const OBJECT_CONSTANT;
 
-    /**
-     * No support for null optional constants
-     * No support for optional constant records
-     * No support for constant binary, list, set, map
-     */
+    /** No support for null optional constants */
+    // No support for optional constant records
+    /** No support for constant binary, list, set, map */
     static constexpr bool DUMMY = false;
 };
 
diff --git a/test-suite/generated-src/pycpp/constants_interface.cpp b/test-suite/generated-src/pycpp/constants_interface.cpp
index 27f93ae56..3633110f7 100644
--- a/test-suite/generated-src/pycpp/constants_interface.cpp
+++ b/test-suite/generated-src/pycpp/constants_interface.cpp
@@ -6,19 +6,19 @@
 
 namespace testsuite {
 
-bool const ConstantsInterface::BOOL_CONSTANT;
+bool constexpr ConstantsInterface::BOOL_CONSTANT;
 
-int8_t const ConstantsInterface::I8_CONSTANT;
+int8_t constexpr ConstantsInterface::I8_CONSTANT;
 
-int16_t const ConstantsInterface::I16_CONSTANT;
+int16_t constexpr ConstantsInterface::I16_CONSTANT;
 
-int32_t const ConstantsInterface::I32_CONSTANT;
+int32_t constexpr ConstantsInterface::I32_CONSTANT;
 
-int64_t const ConstantsInterface::I64_CONSTANT;
+int64_t constexpr ConstantsInterface::I64_CONSTANT;
 
-float const ConstantsInterface::F32_CONSTANT;
+float constexpr ConstantsInterface::F32_CONSTANT;
 
-double const ConstantsInterface::F64_CONSTANT;
+double constexpr ConstantsInterface::F64_CONSTANT;
 
 std::experimental::optional<bool> const ConstantsInterface::OPT_BOOL_CONSTANT = true;
 
diff --git a/test-suite/generated-src/pycpp/constants_interface.hpp b/test-suite/generated-src/pycpp/constants_interface.hpp
index 6c91aa3ed..32cfd3854 100644
--- a/test-suite/generated-src/pycpp/constants_interface.hpp
+++ b/test-suite/generated-src/pycpp/constants_interface.hpp
@@ -62,11 +62,9 @@ class ConstantsInterface {
 
     static ConstantRecord const OBJECT_CONSTANT;
 
-    /**
-     * No support for null optional constants
-     * No support for optional constant records
-     * No support for constant binary, list, set, map
-     */
+    // No support for null optional constants
+    /** No support for optional constant records */
+    // No support for constant binary, list, set, map
     virtual void dummy() = 0;
 };
 
diff --git a/test-suite/generated-src/pycpp/foo_constants.cpp b/test-suite/generated-src/pycpp/foo_constants.cpp
index 2dd7858d3..cf692a0f7 100644
--- a/test-suite/generated-src/pycpp/foo_constants.cpp
+++ b/test-suite/generated-src/pycpp/foo_constants.cpp
@@ -5,19 +5,19 @@
 
 namespace testsuite {
 
-bool const FooConstants::BOOL_CONSTANT;
+bool constexpr FooConstants::BOOL_CONSTANT;
 
-int8_t const FooConstants::I8_CONSTANT;
+int8_t constexpr FooConstants::I8_CONSTANT;
 
-int16_t const FooConstants::I16_CONSTANT;
+int16_t constexpr FooConstants::I16_CONSTANT;
 
-int32_t const FooConstants::I32_CONSTANT;
+int32_t constexpr FooConstants::I32_CONSTANT;
 
-int64_t const FooConstants::I64_CONSTANT;
+int64_t constexpr FooConstants::I64_CONSTANT;
 
-float const FooConstants::F32_CONSTANT;
+float constexpr FooConstants::F32_CONSTANT;
 
-double const FooConstants::F64_CONSTANT;
+double constexpr FooConstants::F64_CONSTANT;
 
 std::string const FooConstants::STRING_CONSTANT = {"string-constant"};
 
diff --git a/test-suite/generated-src/pycpp/foo_constants_interface.cpp b/test-suite/generated-src/pycpp/foo_constants_interface.cpp
index e33cceb37..e544a11d3 100644
--- a/test-suite/generated-src/pycpp/foo_constants_interface.cpp
+++ b/test-suite/generated-src/pycpp/foo_constants_interface.cpp
@@ -6,19 +6,19 @@
 
 namespace testsuite {
 
-bool const FooConstantsInterface::BOOL_CONSTANT;
+bool constexpr FooConstantsInterface::BOOL_CONSTANT;
 
-int8_t const FooConstantsInterface::I8_CONSTANT;
+int8_t constexpr FooConstantsInterface::I8_CONSTANT;
 
-int16_t const FooConstantsInterface::I16_CONSTANT;
+int16_t constexpr FooConstantsInterface::I16_CONSTANT;
 
-int32_t const FooConstantsInterface::I32_CONSTANT;
+int32_t constexpr FooConstantsInterface::I32_CONSTANT;
 
-int64_t const FooConstantsInterface::I64_CONSTANT;
+int64_t constexpr FooConstantsInterface::I64_CONSTANT;
 
-float const FooConstantsInterface::F32_CONSTANT;
+float constexpr FooConstantsInterface::F32_CONSTANT;
 
-double const FooConstantsInterface::F64_CONSTANT;
+double constexpr FooConstantsInterface::F64_CONSTANT;
 
 std::experimental::optional<int32_t> const FooConstantsInterface::OPTIONAL_INTEGER_CONSTANT = 1;
 
diff --git a/test-suite/generated-src/pycpp/return_two.hpp b/test-suite/generated-src/pycpp/return_two.hpp
index abb41f9f0..ae50d8545 100644
--- a/test-suite/generated-src/pycpp/return_two.hpp
+++ b/test-suite/generated-src/pycpp/return_two.hpp
@@ -8,7 +8,7 @@
 
 namespace testsuite {
 
-/** Used for C++ multiple inheritance tests */
+// Used for C++ multiple inheritance tests
 class ReturnTwo {
 public:
     virtual ~ReturnTwo() {}
diff --git a/test-suite/generated-src/pycpp/reverse_client_interface.hpp b/test-suite/generated-src/pycpp/reverse_client_interface.hpp
index 372af04b4..bdbb843f3 100644
--- a/test-suite/generated-src/pycpp/reverse_client_interface.hpp
+++ b/test-suite/generated-src/pycpp/reverse_client_interface.hpp
@@ -15,8 +15,24 @@ class ReverseClientInterface {
 
     virtual std::string return_str() const = 0;
 
+    // Testing code comments before documentation comments
+    // with multiple lines
+    // and another line
+    /**
+     * Testing documentation comments after code comments
+     * with multiple lines
+     * and another line
+     */
     virtual std::string meth_taking_interface(const std::shared_ptr<ReverseClientInterface> & i) = 0;
 
+    /**
+     * Testing documentation comments before code comments
+     * with multiple lines
+     * and another line
+     */
+    // Testing code comments after documentation comments
+    // with multiple lines
+    // and another line
     virtual std::string meth_taking_optional_interface(const std::shared_ptr<ReverseClientInterface> & i) = 0;
 
     static std::shared_ptr<ReverseClientInterface> create();
diff --git a/test-suite/generated-src/pycpp/second_listener.hpp b/test-suite/generated-src/pycpp/second_listener.hpp
index 891774a1d..cbc2eab52 100644
--- a/test-suite/generated-src/pycpp/second_listener.hpp
+++ b/test-suite/generated-src/pycpp/second_listener.hpp
@@ -5,7 +5,7 @@
 
 namespace testsuite {
 
-/** Used for non-C++ multiple inheritance tests */
+// Used for non-C++ multiple inheritance tests
 class SecondListener {
 public:
     virtual ~SecondListener() {}
diff --git a/test-suite/generated-src/python/client_interface.py b/test-suite/generated-src/python/client_interface.py
index 626d1e4e0..c89387407 100644
--- a/test-suite/generated-src/python/client_interface.py
+++ b/test-suite/generated-src/python/client_interface.py
@@ -18,7 +18,10 @@ class ClientInterface(with_metaclass(ABCMeta)):
 
     @abstractmethod
     def get_record(self, record_id, utf8string, misc):
-        """ Returns record of given string """
+        """
+         Testing code comments before documentation comments
+         Returns record of given string
+        """
         raise NotImplementedError
 
     @abstractmethod
@@ -31,6 +34,10 @@ def return_str(self):
 
     @abstractmethod
     def meth_taking_interface(self, i):
+        """
+         Testing documentation comments before code comments
+         This method takes an interface
+        """
         raise NotImplementedError
 
     @abstractmethod
diff --git a/test-suite/generated-src/python/color.py b/test-suite/generated-src/python/color.py
index 1b57533c4..c7266fd68 100644
--- a/test-suite/generated-src/python/color.py
+++ b/test-suite/generated-src/python/color.py
@@ -13,6 +13,11 @@ class Color(IntEnum):
     Red = 0
     Orange = 1
     Yellow = 2
+    """
+     "It is customary to list indigo as a color lying between blue and violet, but it has
+     never seemed to me that indigo is worth the dignity of being considered a separate
+     color. To my eyes it seems merely deep blue." --Isaac Asimov
+    """
     Green = 3
     Blue = 4
     """
diff --git a/test-suite/generated-src/python/constants.py b/test-suite/generated-src/python/constants.py
index 28610e3f4..fbdaae073 100644
--- a/test-suite/generated-src/python/constants.py
+++ b/test-suite/generated-src/python/constants.py
@@ -16,11 +16,13 @@ class Constants:
      Record containing constants
     Constants
         BOOL_CONSTANT: bool_constant has documentation.
-        I8_CONSTANT
+        I8_CONSTANT: i8_constant has a comment
         I16_CONSTANT
         I32_CONSTANT
         I64_CONSTANT
-        F32_CONSTANT
+        F32_CONSTANT: f64_constant has a long comment.
+             (Second line of multi-line comment.
+               Indented third line of multi-line comment.)
         F64_CONSTANT: f64_constant has long documentation.
              (Second line of multi-line documentation.
                Indented third line of multi-line documentation.)
diff --git a/test-suite/generated-src/python/reverse_client_interface.py b/test-suite/generated-src/python/reverse_client_interface.py
index d15a851f7..4ea537ffe 100644
--- a/test-suite/generated-src/python/reverse_client_interface.py
+++ b/test-suite/generated-src/python/reverse_client_interface.py
@@ -18,10 +18,26 @@ def return_str(self):
 
     @abstractmethod
     def meth_taking_interface(self, i):
+        """
+         Testing code comments before documentation comments
+         with multiple lines
+         and another line
+         Testing documentation comments after code comments
+         with multiple lines
+         and another line
+        """
         raise NotImplementedError
 
     @abstractmethod
     def meth_taking_optional_interface(self, i):
+        """
+         Testing documentation comments before code comments
+         with multiple lines
+         and another line
+         Testing code comments after documentation comments
+         with multiple lines
+         and another line
+        """
         raise NotImplementedError
 
     @staticmethod