Thrift: Change docstring syntax.

Summary:
The old docstring syntax collided with the syntax for list constants.
The new syntax looks a lot like doxygent comments.

Trac Bug: #4664

Blame Rev: 32392

Reviewed By: mcslee

Test Plan:
../compiler/cpp/thrift -cpp DocTest.thrift
(with dump_docs on)
and looked at the output.
Generated C++ is identical to installed thrift.

Revert Plan: ok


git-svn-id: https://svn.apache.org/repos/asf/incubator/thrift/trunk@665182 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 106 insertions, 19 deletions

diff --git a/test/DocTest.thrift b/test/DocTest.thrift
index 682edffe0..c06bd212b 100755
--- a/test/DocTest.thrift
+++ b/test/DocTest.thrift
@@ -6,14 +6,14 @@ cpp_namespace thrift.test
 
 # the new unix comment
 
-[Some doc text goes here.  Wow I am [nesting these].]
+/** Some doc text goes here.  Wow I am [nesting these] (no more nesting.) */
 enum Numberz
 {
 
-  [This is how to document a parameter]
+  /** This is how to document a parameter */
   ONE = 1,
 
-  [And this is a doc for a parameter that has no specific value assigned]
+  /** And this is a doc for a parameter that has no specific value assigned */
   TWO,
 
   THREE,
@@ -22,17 +22,17 @@ enum Numberz
   EIGHT = 8
 }
 
-[This is how you would do a typedef doc]
+/** This is how you would do a typedef doc */
 typedef i64 UserId 
 
-[And this is where you would document a struct]
+/** And this is where you would document a struct */
 struct Xtruct
 {
 
-  [And the members of a struct]
+  /** And the members of a struct */
   1:  string string_thing
 
-  [doct text goes before a comma]
+  /** doct text goes before a comma */
   4:  byte   byte_thing,
 
   9:  i32    i32_thing,
@@ -46,14 +46,14 @@ struct Xtruct2
   3: i32    i32_thing
 }
 
-[Struct insanity]
+/** Struct insanity */
 struct Insanity
 {
 
-  [This is doc for field 1]
+  /** This is doc for field 1 */
   1: map<Numberz, UserId> userMap,
 
-  [And this is doc for field 2]
+  /** And this is doc for field 2 */
   2: list<Xtruct> xtructs 
 }
 
@@ -73,17 +73,17 @@ struct OneField {
   1: EmptyStruct field
 }
 
-[This is where you would document a Service]
+/** This is where you would document a Service */
 service ThriftTest
 {
 
-  [And this is how you would document functions in a service]
+  /** And this is how you would document functions in a service */
   void         testVoid(),
   string       testString(1: string thing),
   byte         testByte(1: byte thing),
   i32          testI32(1: i32 thing),
 
-  [Like this one]
+  /** Like this one */
   i64          testI64(1: i64 thing),
   double       testDouble(1: double thing),
   Xtruct       testStruct(1: Xtruct thing),
@@ -92,10 +92,10 @@ service ThriftTest
   set<i32>     testSet(1: set<i32> thing),
   list<i32>    testList(1: list<i32> thing),
 
-  [This is an example of a function with params documented]
+  /** This is an example of a function with params documented */
   Numberz      testEnum(
 
-    [This param is a thing]
+    /** This param is a thing */
     1: Numberz thing
 
   ),
@@ -120,7 +120,94 @@ service ThriftTest
   Xtruct testMultiException(string arg0, string arg1) throws(Xception err1, Xception2 err2)
 }
 
-service SecondService
-{
-  void blahBlah()
-}
+/// This style of Doxy-comment doesn't work.
+typedef i32 SorryNoGo
+
+/**
+ * This is a trivial example of a multiline docstring.
+ */
+typedef i32 TrivialMultiLine
+
+/**
+ * This is the cannonical example
+ * of a multiline docstring.
+ */
+typedef i32 StandardMultiLine
+
+/**
+ * The last line is non-blank.
+ * I said non-blank! */
+typedef i32 LastLine
+
+/** Both the first line
+ * are non blank. ;-)
+ * and the last line */
+typedef i32 FirstAndLastLine
+
+/**
+ *    INDENTED TITLE
+ * The text is less indented.
+ */
+typedef i32 IndentedTitle
+
+/**       First line indented.
+ * Unfortunately, this does not get indented.
+ */
+typedef i32 FirstLineIndent
+
+
+/**
+ * void code_in_comment() {
+ *   printf("hooray code!");
+ * }
+ */
+typedef i32 CodeInComment
+
+    /**
+     * Indented Docstring.
+     * This whole docstring is indented.
+     *   This line is indented further.
+     */
+typedef i32 IndentedDocstring
+
+/** Irregular docstring.
+ * We will have to punt
+  * on this thing */
+typedef i32 Irregular1
+
+/**
+ * note the space
+ * before these lines
+* but not this
+ * one
+ */
+typedef i32 Irregular2
+
+/**
+* Flush against
+* the left.
+*/
+typedef i32 Flush
+
+/**
+  No stars in this one.
+  It should still work fine, though.
+    Including indenting.
+    */
+typedef i32 NoStars
+
+/** Trailing whitespace   
+Sloppy trailing whitespace   
+is truncated.   */
+typedef i32 TrailingWhitespace
+
+/**
+ * This is a big one.
+ *
+ * We'll have some blank lines in it.
+ * 
+ * void as_well_as(some code) {
+ *   puts("YEEHAW!");
+ * }
+ */
+typedef i32 BigDog