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
diff --git a/test/DocTest.thrift b/test/DocTest.thrift
index 682edff..c06bd21 100755
--- a/test/DocTest.thrift
+++ b/test/DocTest.thrift
@@ -6,14 +6,14 @@
# 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 @@
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 @@
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 @@
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 @@
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 @@
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